Aidefile

The Aidefile is a TOML config file that turns a Claude Code project into an agent. Place it in the project root.

Full example

[persona]
name = "Senior Reviewer"
style = "direct, cares about edge cases"

[budget]
tokens = "100k"
max_retries = 3

[memory]
compact_after = "200k"

[hooks]
on_spawn = ["inject-vault"]
on_complete = ["commit-memory"]

[skills]
include = ["code-review"]

[trigger]
on = "issue"

[vault]
keys = ["GITHUB_TOKEN", "SLACK_WEBHOOK"]

[output]
max_summary_tokens = 500
narrative_schema = """
NOTES: <one-line what you changed>
PR: <url or none>
NEXT: <optional redirect>
"""

[workspace]
read = ["~/claude_projects/crossmem-bridge", "~/claude_projects/crossmem-chrome"]

Sections

[persona]

FieldTypeDefaultDescription
namestring"unnamed"Agent display name
stylestring—Personality hint (injected into CLAUDE.md context)

[budget]

FieldTypeDefaultDescription
tokensstring"200k"Token limit per task. Supports "100k", "1m", or raw numbers.
max_retriesinteger3Maximum retry attempts if task doesn't complete in one invocation

[memory]

FieldTypeDefaultDescription
compact_afterstring—Auto-compact memory when estimated tokens exceed this threshold

[hooks]

FieldTypeDescription
on_spawnlist of stringsRun before the task starts
on_completelist of stringsRun after the task finishes

Built-in hooks:

  • "inject-vault" — decrypt and inject vault secrets (handled automatically by the runner)
  • "commit-memory" — git add + commit the memory/ directory

Custom hooks are shell commands run in the agent's directory.

[skills]

FieldTypeDescription
includelist of stringsSkill names to load from the skills/ directory

[trigger]

FieldTypeDescription
onstringTrigger type: "manual", "issue", or "cron:EXPR"

[vault]

FieldTypeDescription
keyslist of stringsSecret names to decrypt and inject as env vars

[output]

[output]
max_summary_tokens = 500
narrative_schema = """
NOTES: <one-line what you changed>
PR: <url or none>
NEXT: <optional redirect>
"""
FieldTypeDefaultDescription
max_summary_tokensu32500Max tokens in the bounded summary
narrative_schemastring(default NOTES/PR/NEXT)Template the sub-agent fills in inside <aide-summary> block

This section is load-bearing for aide-as-subagent mode. Without it, sub-agent output pollutes the frontier context. The runner wraps the task with instructions requiring the sub-agent to emit an <aide-summary> block conforming to the narrative_schema. The bounded summary is what aide wait returns to the calling agent, keeping the frontier context clean.

[workspace]

[workspace]
read = ["~/claude_projects/crossmem-bridge", "~/claude_projects/crossmem-chrome"]
FieldTypeDefaultDescription
readlist of strings[]Sibling directories the sub-agent can read

The read list is translated to .claude/settings.json permission grants and a WORKSPACE section in the task prompt. This solves sandbox restrictions in non-interactive claude -p mode, where the sub-agent would otherwise be unable to access files outside its own project directory.

Token shorthand

The tokens and compact_after fields accept shorthand:

InputValue
"100k"100,000
"1m"1,000,000
"50000"50,000

Minimal Aidefile

Only [persona] is required:

[persona]
name = "Helper"

Everything else has sensible defaults (200k token budget, manual trigger, no vault).