---
title: "System Prompt Customization"
source: https://docs.autohand.ai/working-with-autohand-code/system-prompt
---

# System Prompt Customization

Customize or replace the default system prompt to tailor the agent's behavior, personality, constraints, and output style for your specific needs.

## 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:

``` bash
# 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.

**Warning:** Replacing the system prompt removes all built-in safety guidelines, tool instructions, and behavioral constraints. Use this only when you need complete control over agent behavior.

## Appending to the system prompt

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

``` bash
# 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.

``` bash
# 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

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

### Domain-specific assistant

``` bash
# 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

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

### CI/CD integration

``` bash
# 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.

**Tip:** For most use cases, prefer `--append-sys-prompt` over `--sys-prompt`. Appending preserves the agent's built-in capabilities while adding your specific requirements.