Avalon

한국어 | English

Avalon is a personal agent document management harness. It helps Codex, Claude Code, and other agents create, link, index, search, and optionally Git-manage durable Markdown documents for long-running work.

Avalon does not own the agent goal loop. The agent owns the goal; Avalon provides the document system that keeps plans, progress, reviews, verification, and follow-up work readable after the chat scrollback is gone.

Why Avalon

Agent work often needs more than a transcript. A useful work record should be a document that a person can inspect, edit, link, version, and resume from another session.

Avalon is built around these ideas:

• work documents are a document type, not a forced task binding workflow.
• ~/.avalon stores configuration and runtime support, but is not a Git repository.
• document type directories can be inside shared or separate Git repositories.
• commit and push are explicit commands only.
• follow-up work creates a new linked document instead of rewriting old history.

Quick Start

Requirements:

• Node.js 24 or newer.
• npm.
• Codex or Claude Code with plugin support.

Install the package:

npm install -g @crispebble/avalon

Run setup and choose the agent integrations to configure:

avalon setup

For non-interactive setup, pass an explicit target:

avalon setup --agent codex
avalon setup --agent claude
avalon setup --agent both
avalon setup --agent none

avalon setup --agent codex wires the Codex plugin cache, marketplace, MCP server, and skills. Restart Codex after setup completes.

avalon setup --agent claude creates a local Claude Code marketplace and installs the Avalon plugin from the npm package source. Restart or reload Claude Code plugins after setup completes.

The legacy Codex installer is still available:

PACKAGE_ROOT="$(npm root -g)/@crispebble/avalon"
sh "$PACKAGE_ROOT/scripts/install-codex.sh" --package-root "$PACKAGE_ROOT" --skip-npm-install

npm install itself does not modify Codex or Claude Code settings. Agent setup happens only when you explicitly run avalon setup or a setup script.

For local development from this repository:

npm run build
node dist/cli.js setup --agent both --package-root "$PWD"

Initialize the local Avalon config:

avalon init --json

By default, work documents live under ~/.avalon/documents/work_documents. Avalon does not run git init in ~/.avalon.

Work Documents

Create a new work document:

avalon work new --title "Implement document management OS" --description "Pivot Avalon to work documents" --json

Continue from a previous work document:

avalon work continue --previous ~/.avalon/documents/work_documents/work/2026/05/example.md --title "Follow-up implementation" --json

Search and regenerate indexes:

avalon work search --query "document management" --json
avalon work index --json

Work documents use frontmatter with previous_work_docs and related_work_docs so follow-up work can point back without rewriting historical documents.

Document Git

Document Git policy is configured per document type. Multiple document types may share the same Git repo root.

avalon docs git init --kind work_documents --remote [email protected]:me/agent-docs.git --branch main --json
avalon docs status --kind work_documents --json
avalon docs commit --kind work_documents --message "docs(work-documents): record implementation plan" --json
avalon docs push --kind work_documents --json

Commit and push never happen automatically.

Product Surface

Avalon ships as the public npm package @crispebble/avalon.

avalon     CLI for document setup, work documents, indexes, and document Git
avalon-mcp MCP stdio server for agent tools

The Codex and Claude Code plugin bundles include MCP tools and focused skills for setup, work documents, and document maintenance.

Distribution Status

The package contains Codex and Claude plugin files, compiled CLI/MCP entrypoints, skills, installer, README files, and license. Local development files such as docs/, tests/, .idea/, and AGENTS.md stay outside the npm tarball.

Release policy, branch strategy, versioning, and publish mechanics are documented in RELEASE.md. Project operation rules for contributors and agents are documented in AGENTS.md.

License

MIT. See LICENSE.