System Prompt Customization

Overview

The system prompt is the foundational instruction set that shapes how the agent behaves. Autohand ships with a carefully crafted default prompt, but you can customize it for specialized use cases.

There are two approaches:

• Replace — Swap out the entire system prompt with your own
• Append — Add instructions to the end of the default prompt

Replacing the system prompt

Use --sys-prompt to completely replace the default system prompt:

# Inline text
autohand --sys-prompt "You are a senior Python developer. Always use type hints and write docstrings."

# From a file
autohand --sys-prompt ./prompts/python-expert.md

Autohand auto-detects whether the value is a file path or inline text. If the value points to an existing file, its contents are used as the system prompt.

Appending to the system prompt

Use --append-sys-prompt to add instructions without removing the defaults:

# Add inline instructions
autohand --append-sys-prompt "Always write tests for new functions. Prefer vitest over jest."

# Append from a file
autohand --append-sys-prompt ./prompts/team-guidelines.md

This is the safer option — you keep all built-in behavior while adding your own constraints on top.

File path detection

Both flags auto-detect file paths. Autohand checks if the value:

1. Ends with a common extension (.md, .txt, .prompt)
2. Points to an existing file on disk

If either condition is true, the file contents are used. Otherwise, the value is treated as inline text.

# These read from files:
autohand --sys-prompt ./my-prompt.md
autohand --append-sys-prompt /absolute/path/to/guidelines.txt

# These use inline text:
autohand --sys-prompt "Be concise and direct"
autohand --append-sys-prompt "Always explain your reasoning"

Use cases

Team coding standards

# Append team guidelines to every session
autohand --append-sys-prompt ./team/coding-standards.md

Domain-specific assistant

# Create a specialized data engineering assistant
autohand --sys-prompt "You are a data engineering expert. Focus on SQL optimization, ETL pipelines, and data modeling. Use dbt best practices."

Output formatting

# Force specific output style
autohand --append-sys-prompt "Always respond in bullet points. Keep explanations under 3 sentences."

CI/CD integration

# Strict mode for automated pipelines
autohand --sys-prompt ./ci/review-prompt.md \
  --restricted \
  -p "Review staged changes for security issues"

Precedence rules

System prompt components are assembled in this order:

1. Base prompt — Default system prompt (or --sys-prompt replacement)
2. AGENTS.md — Project-level instructions from your AGENTS.md file
3. Memory — Stored memories from /memory and # entries
4. Append prompt — Content from --append-sys-prompt
5. Tool schemas — Auto-generated tool definitions

When using --sys-prompt, items 2-4 still apply unless the replacement prompt explicitly handles them.