Agentspec Usage

agentspec

agentspec keeps one canonical copy of your agent resources in ~/.agents/ and renders them into explicitly selected AI coding tools. Register a resource once, then choose its destinations with manage link or manage add --tools.

Run agentspec --help for the command map, or agentspec commands --format json for the full tree as machine-readable JSON.

Output format

Human-readable by default. Every command takes the global --format json flag. There is no per-command --json flag.

agentspec status --format json
agentspec mcp list --format json

Progress chatter goes to stderr; --format json writes exactly one JSON document to stdout, so it is always safe to pipe into jq.

The canonical store

Tools get real copies of the store version by default; --symlink opts into relative symlinks for skills. Agents are always rendered copies. Adoption never modifies or deletes the original.

Start here

agentspec sync --adopt      # discover → adopt → repair selected links → verify
agentspec status            # what is managed, what is not
agentspec                   # interactive TUI

sync is the default entry point. It adopts untracked resources, re-copies local-sourced ones from their origin, repairs tracked links without enabling resources in additional tools, adopts MCP servers found in project .mcp.json files and tool configs, and verifies SHA-256 hashes.

Skills and agents

agentspec manage add owner/repo --all-tools        # from GitHub
agentspec manage add ./my-skill --all-tools        # from a local path
agentspec manage add owner/repo#branch@subdir      # branch and subpath
agentspec manage list                              # what is managed
agentspec manage link <name> <tool-slug>           # link one resource to one tool
agentspec manage verify                            # checksum integrity
agentspec manage create <name> --kind skill        # scaffold from template
agentspec prune -y                                 # drop broken links

Kind is auto-detected; pass --kind only to override.

MCP servers

One definition, every tool, whatever dialect that tool speaks — mcpServers JSON, Amp's amp.mcpServers key, Codex's [mcp_servers.<name>] TOML tables, or OpenCode's mcp key. agentspec translates on write.

agentspec mcp add sr --command sr --args "mcp serve"      # stdio server
agentspec mcp add api --url https://mcp.example/sse --type http
agentspec mcp add sr --command sr --tool github-copilot   # one tool only
agentspec mcp list                                         # store + per-tool state
agentspec mcp doctor                                       # every target, path, dialect
agentspec mcp adopt                                        # pull tool-native servers into the store
agentspec mcp sync                                         # push the store to every tool
agentspec mcp unlink sr --tool cursor                      # remove from one tool
agentspec mcp remove sr                                    # remove everywhere

mcp doctor is the first thing to run when a server is not showing up: it lists every MCP-capable tool, whether it is installed, its config path, and its dialect.

Finding past sessions

session search scans transcripts from Claude Code, Codex, GitHub Copilot, and Gemini CLI. Filter before you read.

# What did I ask about rate limiting, in my own words only?
agentspec session search "rate limit" --role user

# Last week's Copilot work in one repo, as JSON
agentspec session search --source copilot --project agentspec --since 7d --format json

# Sessions that ran a specific tool, or touched a specific file
agentspec session search --tool-used Bash --limit 50
agentspec session search "panic" --file src/mcp/mod.rs

# Regex, more hits per session, wider excerpts
agentspec session search "cargo\s+build" --regex --hits 10 --context 400

Every JSON result carries an export_command, so the follow-up is mechanical:

agentspec session search "flaky test" --role user --format json \
  | jq -r '.results[0].export_command' | sh

Other session verbs:

agentspec session list                    # newest sessions across all sources
agentspec session list --source claude --limit 50
agentspec session find                    # interactive fuzzy picker
agentspec session export claude --last -o handoff.md
agentspec session sync claude codex --last # portable handoff staged for another tool

Everything else

agentspec project sync                 # AGENTS.md / CLAUDE.md / llms.txt into the store
agentspec manage memory --pull         # pull tool memories into ~/.agents/memories
agentspec permissions init && agentspec permissions sync
agentspec hooks add ./on-stop.sh && agentspec hooks link on-stop.sh --all-tools
agentspec plugins export
agentspec worktree create <name>       # <repo>/.worktrees/<name>
agentspec fleet doctor                 # multi-agent fleet backend check

Gotchas

• --format json is global and must be accepted anywhere, but only commands that produce data emit JSON; action commands report progress on stderr.
• manage add skips a name that already exists — first installed wins. Remove it first to replace it.
• A tool counts as installed when any of its config directories exists. Run agentspec mcp doctor to see what agentspec thinks is present.
• Adoption is non-destructive: originals are never edited or deleted, and a definition already in the store wins over a tool-native or project one.