Modify the system prompt

The CLI ships with a default system prompt. You have two ways to influence it: append your own guidance on top, or replace it entirely. Append is the right default for most integrations.

Append vs replace

  • Append: keep the CLI defaults and add your own coding standards, repo conventions, or persona. Recommended.
  • Replace: take full control of the system prompt. Only do this if you have a strong reason; you lose the CLI's built-in tool guidance, safety rules, and formatting.

Both methods accept either inline text or a file path. The file path mirrors the CLI's `--sys-prompt` / `--append-system-prompt` flags.

Append to the default prompt

Use this for repo-specific rules, brand voice, or workflow guardrails.

TypeScript

import { AutohandSDK } from '@autohandai/agent-sdk';

const sdk = new AutohandSDK({ cwd: '.' })
  .appendSystemPrompt(
    "Always run bun run typecheck before declaring a fix complete."
  );

await sdk.start();

Python

from autohand_sdk import AutohandSDK

sdk = AutohandSDK(
    cwd=".",
    append_system_prompt="Always run uv run pytest before declaring a fix complete.",
)
await sdk.start()

Go

sdk := autohand.NewSDK(&autohand.Config{
    CWD: ".",
    AppendSystemPrompt: "Always run go test ./... before declaring a fix complete.",
})
_ = sdk.Start(ctx)

Java

AutohandSDK sdk = new AutohandSDK(SDKConfig.builder()
    .cwd(".")
    .appendSystemPrompt("Always run mvn test before declaring a fix complete.")
    .build());
sdk.start();

Swift

let agent = Agent(
    name: "Reviewer",
    instructions: "Always run swift test before declaring a fix complete.",
    tools: [.readFile, .bash],
    model: ModelID("gpt-4o"),
    provider: OpenAIProvider(apiKey: "sk-...")
)

The TypeScript and Python SDKs also accept a file path. Anything that looks like a path is read from disk; everything else is treated as inline text.

TypeScript

const sdk = new AutohandSDK({ cwd: '.' })
  .appendSystemPrompt('./prompts/release-readiness.md');

Python

sdk = AutohandSDK(
    cwd=".",
    append_system_prompt="./prompts/release-readiness.md",
)

Replace the default prompt

Use this only when you need to fully define the agent's behaviour. You are responsible for tool guidance, safety rules, and output formatting.

TypeScript

import { AutohandSDK } from '@autohandai/agent-sdk';

const sdk = new AutohandSDK({ cwd: '.' })
  .setSystemPrompt('./SYSTEM_PROMPT.md');

await sdk.start();

Python

from autohand_sdk import AutohandSDK

sdk = AutohandSDK(
    cwd=".",
    system_prompt="./SYSTEM_PROMPT.md",
)
await sdk.start()

Go

sdk := autohand.NewSDK(&autohand.Config{
    CWD: ".",
    SystemPrompt: "./SYSTEM_PROMPT.md",
})

Java

AutohandSDK sdk = new AutohandSDK(SDKConfig.builder()
    .cwd(".")
    .systemPrompt("./SYSTEM_PROMPT.md")
    .build());

Per-agent instructions

The high-level `Agent.create()` API takes an `instructions` field that becomes part of the appended prompt. Use this for short-lived agents that need a focused persona.

TypeScript

import { Agent } from '@autohandai/agent-sdk';

const agent = await Agent.create({
  cwd: '.',
  instructions: 'You review code with Staff-level TypeScript judgement. Prefer Bun.',
});

const result = await agent.run('Review the changes in src/auth/');

Python

# The Python SDK uses append_system_prompt directly.
sdk = AutohandSDK(
    cwd=".",
    append_system_prompt="You review code with Staff-level Python judgement. Prefer uv.",
)

Go

agent, _ := autohand.NewAgent(ctx, &autohand.Config{
    CWD: ".",
    AppendSystemPrompt: "You review code with Staff-level Go judgement.",
})

Java

Agent agent = Agent.create(AgentOptions.builder()
    .cwd(".")
    .instructions("You review code with Staff-level Java judgement.")
    .build());

Best practices

  • Default to appending. Replacing is rarely the right answer.
  • Keep prompts in files under version control. Put them next to the code they govern.
  • Be specific about success criteria (“tests pass”, “file compiles”) so the agent knows when it can stop.
  • State what the agent should not do. “Do not edit migration files” is more useful than a long list of allowed paths.
  • If you maintain multiple agents, share a base prompt and append per-agent overrides on top.