Agent Spec

Agent Spec is a CLI-first open source project for managing AI agent configuration across tools.

The current MVP treats Claude-style configuration as the canonical base, then helps import, push, and pull that configuration across:

• Claude Code
• Codex
• OpenCode

Agent Spec is local-first and GitHub-backed. It uses normal files, normal Git commits, and the GitHub CLI (gh) instead of a hosted sync service.

Why

AI agent tools use different conventions for prompts, skills, MCP servers, plugins, and runtime configuration.

That creates drift:

• CLAUDE.md may contain one set of instructions.
• AGENTS.md may contain another.
• Skills may live in different folders depending on the tool.
• Moving to another machine often means copying the same files again.

Agent Spec gives those files one Git-backed home and provides adapters for the tools you use locally.

Current Behavior

Import and Merge

agentspec init and agentspec push scan supported local tool config directories and merge them into one workspace.

Prompt files are appended into the canonical CLAUDE.md with source headings:

## From Claude Code

...

## From Codex

...

## From OpenCode

...

Shared folders such as skills/, mcp/, and plugins/ are also merged into the Claude-style workspace folders when present. This applies to both init and push, so changes made under Codex or OpenCode are still collected into the canonical Agent Spec repository.

Pull

agentspec pull applies the canonical workspace back to supported local tools.

Agent Spec stores its canonical workspace at ~/.agentspec. By default, agentspec pull and agentspec sync pull that workspace repository and overwrite discovered local tool config directories such as ~/.claude, ~/.codex, and ~/.config/opencode. For inspection or testing, use --output-dir to write converted files somewhere else.

Install

For development:

npm install
npm run build

Install from npm:

npm install -g @eddyli1989/agent-spec
agentspec --help

Run the compiled CLI:

node dist/src/cli.js --help

Build a standalone binary with Bun:

npm run build:binary
./dist-bin/agentspec --help

Requirements

• Node.js for development.
• Bun for standalone binary builds.
• Git.
• GitHub CLI (gh) for auth and init.

Authenticate with GitHub:

gh auth login

or:

agentspec auth

Commands

agentspec init [--offline]
agentspec push
agentspec pull [--output-dir <dir>]
agentspec sync [--output-dir <dir>]
agentspec auth
agentspec doctor
agentspec --help

init

Scans supported local tool configuration, merges it into an Agent Spec workspace, creates a GitHub repository, commits the initial files, and pushes them.

The workspace is always stored at ~/.agentspec.

Use --offline to skip GitHub repository creation and Git commands. Offline init only merges discovered local configuration into ~/.agentspec.

The default repository name is agent-spec. If that repository already exists and looks like an Agent Spec configuration repository, Agent Spec clones it into the home workspace. If it exists but appears to be a source repository or another unrelated project, Agent Spec falls back to numbered names such as agent-spec-01, agent-spec-02, and so on.

agentspec init
agentspec init --offline

push

Pulls the workspace, rescans local configuration, merges changes, and pushes a new commit only when files changed.

agentspec push

agentspec update is currently kept as a compatibility alias for agentspec push.

pull

Pulls the workspace and applies the canonical configuration to supported tools found on the machine.

agentspec pull
agentspec sync

Inspect converted output without touching real tool config directories:

agentspec pull --output-dir /tmp/agent-spec-output

agentspec sync is currently kept as a compatibility alias for agentspec pull.

auth

Delegates GitHub authentication to gh auth login.

agentspec auth

doctor

Currently a placeholder for future environment checks.

agentspec doctor

Testing

npm test
npm run build
npm run build:binary

Project Status

Agent Spec is early MVP software.

Implemented:

• CLI command dispatch.
• Tool discovery for Claude Code, Codex, and OpenCode.
• Prompt merge into canonical CLAUDE.md.
• Merging of skills/, mcp/, and plugins/ into Claude-style workspace folders when present.
• GitHub repository creation through gh.
• Offline init for local-only config merging.
• Existing repository recovery during init.
• Default home workspace at ~/.agentspec.
• pull --output-dir for safe inspection.
• Standalone binary build through Bun.

Not implemented yet:

• Conflict resolution beyond simple append/copy behavior.
• Prompt de-duplication.
• Rich MCP format adaptation.
• Secret handling.
• Desktop UI.
• Release packaging for all platforms.

Design Notes

See PROPOSAL.md for the project proposal and longer-term direction.