agent-smith-cli

Agent Smith 🕶️

Smith your AGENTS.md file.
Build living agent instructions from the project sources you already maintain.

uv tool install agent-smith-cli

The problem

Agent instructions drift when they are maintained separately from the project. Commands change, tools move on and architecture decisions accumulate, while a hand-written AGENTS.md quietly becomes incomplete or misleading. One-off generation only postpones the same problem.

Agent instructions should evolve with the sources that already describe the project, without surrendering control of the result.

How Agent Smith solves it

Run agent-smith at your project root. It rebuilds AGENTS.md from your README overview, your mise tool declarations, documented just commands, architecture decision filenames and optional custom extractors.

The result is deterministic, repeatable Markdown: update the sources you own, regenerate the instructions and review an ordinary diff. No nondeterministic /init step to rerun, no tokens spent on a task a deterministic tool can handle, and no second document to keep in sync.

Demo

[!NOTE] Agent Smith is available on PyPI. It is under active development; versions remain below 1.0.

[!TIP] See the real output: our generated AGENTS.md. We eat our own dog food: Agent Smith generates this repository's agent instructions from its own project sources.

Install

The PyPI distribution is named agent-smith-cli; the executable remains agent-smith.

Agent Smith supports Python 3.11–3.15. Install the published CLI from PyPI with uv:

uv tool install agent-smith-cli

This installs the command in an isolated environment.

[!TIP] If uv reports that its tool directory is missing from your PATH, run uv tool update-shell and restart your terminal.

Alternatively, install with pip in an activated Python virtual environment:

python -m pip install agent-smith-cli

Run and verify

agent-smith --version
agent-smith --help
agent-smith

[!TIP] To confirm installation, check that --version prints the installed Agent Smith version and --help displays the available options. Both should exit successfully.

Run the command from the root of the project you want to document. It creates or replaces AGENTS.md in that directory. Successful generation is silent; open the file to verify the result. No configuration is needed when you follow the conventions below.

agent-smith
cat AGENTS.md

Use agent-smith --output instructions.md to choose another output filename. The document has an H1 containing its filename, an H2 for each section and a quoted footer identifying the command that produced that section.

Conventions

# My project

Describe what the project does and why someone would use it.

## Installation

This section is outside the extracted overview.

[tools]
python = ["3.14", "3.11"]
uv = "latest"
node = { version = "lts", postinstall = "corepack enable" }

## Main tech stack

- `python` — `3.14`, `3.11`
- `uv` — `latest`
- `node` — `lts`

# List the project's available commands.
[group("Help")]
help:
    @just --list

# Check modified files for whitespace errors.
[group("Quality")]
check-whitespace:
    git diff --check

## Available commands

### Help

- `just help` — List the project's available commands.

### Quality

- `just check-whitespace` — Check modified files for whitespace errors.

## Architecture decisions

Directory: `docs/adr`

- `0001-record-architecture-decisions`
- `0002-use-python`

Configure sections

An optional root agent-smith.toml customizes built-in sections and adds custom extractors. For example, to enable the four built-ins and append tracked files:

output = "AGENTS.md"

[overview]
enabled = true
source = "README.md"
title = "Overview"

[available_commands]
enabled = true
title = "Available commands"
command = "just help"

[tech_stack]
enabled = true
source = "mise.toml"
title = "Main tech stack"

[architecture_decisions]
enabled = true
title = "Architecture decisions"

[[sections]]
title = "Tracked files"
command = "git ls-files"

Each custom section uses its command's UTF-8 stdout as Markdown, followed by a footer with the exact command. Sections appear in configuration order after the built-in overview, main tech stack, available commands and architecture decisions. Set [available_commands].enabled = false to disable command discovery, or change its command to another source of standard just list output, such as just --list. Explicit enabled = true requires the command to work even if no root justfile was detected.

Add multiple custom sections

In TOML, double brackets such as [[sections]] add an item to an array of tables: here, a list of custom sections. Repeat that exact header for each section, followed by its own title and command. You do not need to number the headers or give them different names.

For example, use these three blocks in agent-smith.toml:

[[sections]]
title = "Tracked files"
command = "git ls-files"

[[sections]]
title = "Development guidelines"
command = "cat docs/development.md"

[[sections]]
title = "Project context"
command = "bash scripts/project-context.sh"

Supply the referenced files and scripts, then run agent-smith. It appends these three sections after the built-ins, in the order shown. Each command's stdout becomes the Markdown body under its section's H2 heading, with a footer recording the command. Any executable can provide the content; Python is not required.

Control section order

The generated document follows this order, omitting disabled or undetected built-ins:

1. Overview
2. Main tech stack
3. Available commands
4. Architecture decisions
5. Custom sections, in the order of their [[sections]] blocks

To reorder custom sections, move their entire [[sections]] blocks in agent-smith.toml. For example, moving the "Project context" block above "Tracked files" makes it appear first among the custom sections.

[!NOTE] Built-in order is currently fixed. Moving [overview], [tech_stack], [available_commands] or [architecture_decisions] in the TOML file does not change their output order. Custom sections cannot currently be inserted before or between built-ins, and there is no order or position setting.

Replace a built-in section

To replace the overview with your own extractor:

[overview]
enabled = false

[[sections]]
title = "Overview"
command = "./scripts/my-overview.sh"

Supply your own script for that command. You can also disable the built-in with --no-overview, and select another configuration with --config path/to/config.toml. --output takes precedence over configuration. Paths and command working directories are relative to where you invoke the CLI, including with --config. The output's parent directory must exist.

[!WARNING] The help recipe and custom commands run with your permissions. Only generate documents from trusted projects and configurations. If extraction or writing fails, Agent Smith preserves the existing output file; side effects of custom scripts are not rolled back.

[!NOTE] Identical configuration and extractor outputs produce identical Markdown. Variable command output, such as timestamps, remains variable. Extraction preserves relative links and does not copy reference definitions from outside the overview. No Markdown formatter is applied.

Contributing

See CONTRIBUTING.md for repository setup, development commands, commit conventions and just-in-time architecture decisions. The license is MIT.