Agent Smith
eliharoun/agent-smith
Autor uma vez, valide, instale em qualquer plataforma de agentes de código
Ver no GitHubGerenciador de ciclo de vida para agentes de IA em codificação. Permite autoria única de agentes com validação de esquema e instalação em múltiplas plataformas (OpenCode, Claude Code, Codex, Kiro) via bundle versionado em controle de fonte.
Instalação
npx convez-ai eliharoun/agent-smith1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Criar agentes de codificação reutilizáveis e versionados
- Distribuir agentes especializados entre múltiplas IDEs e plataformas
- Compilar conhecimento sob demanda com AGENTS.md padrão
- Auditar e manter consistência de agentes com esquema rigoroso
Veredito

Solução sólida para times que precisam escalar agentes de IA entre plataformas fragmentadas. A abordagem de bundle com validação rigorosa resolve um problema real, mas exige curva de aprendizado e infraestrutura Bun estabelecida. Ideal para organizações com frota ativa de agentes especializados.
README
A tradução para o português deste README ainda está na fila.
Why
AI coding tools are moving from a single general assistant to fleets of specialized agents. Each platform — OpenCode, Claude Code, Codex, Kiro — defines them differently: different files, frontmatter, permissions, tool names, and discovery rules. Useful agents become hard to share, audit, version, and keep consistent.
agent-smith treats an agent as a source-controlled bundle. Author once as four files. Validate against a strict schema. Install into every platform with one command.
Define a bundle:
IDENTITY.md— who the agent is and when to use itEXPERTISE.md— what the agent knows, checks, and optimizes forSOUL.md— how the agent behaves, communicates, and makes tradeoffsagent.config.json— targets, model tier, mode, permissions, MCP servers, skills, knowledge sources (including URLs routed through declared MCP tools)
Then smith agent install emits the right native config for every platform you target.
A fifth target, agents-md, emits a single AGENTS.md — the cross-tool standard that Cursor, Windsurf, GitHub Copilot, Aider, Codex CLI, Devin, Junie, Roo, Zed, Warp, and Gemini CLI all read. Bundles whose materialized knowledge would overflow the inline budget auto-compile into a TOC stanza + on-demand fetch (smart default — smith decides, you can override). URLs routed through declared MCP tools are materialized as clean markdown with provenance frontmatter. One bundle reaches every AGENTS.md-aware runtime with progressive-disclosure pointers instead of inlined-and-truncated prose. See guide/16 — Knowledge compiler.
"Me. Me. Me too." — Agent Smith
Install
Quickstart (recommended)
Requires Bun >= 1.1.0. agent-smith runs on the Bun runtime; it does not work under Node.
# Install bun if you don't have it (https://bun.sh)
curl -fsSL https://bun.sh/install | bash
# Install agent-smith from npm
npm install -g @eliharoun/agent-smith
# Initialize state and verify
smith init
smith status
The npm install postinstall runs a brief bootstrap that copies the bundled the-architect and the-keymaker skills into the per-platform skill directories (set AGENT_SMITH_SKIP_POSTINSTALL=1 to skip). When bun is not on your PATH, the postinstall prints a one-line hint and exits cleanly — the package installs but doesn't bootstrap until bun is available.
After install, verify:
smith doctor
From source (for development)
npm install -g @eliharoun/agent-smith gives you both the CLI and smith gui (the local browser control panel) — the GUI ships in the package (Bun is required at runtime, as for the rest of the CLI). The from-source path is for developing agent-smith itself or hacking on the GUI source. Clone and bootstrap:
gh repo clone eliharoun/agent-smith
cd agent-smith
bash bin/install
bin/install clones to ~/.agent-smith/, runs bun install, builds the GUI SPA bundle, symlinks ~/.local/bin/smith, and adds ~/.local/bin to your PATH via a marker block in your shell rc. The same smith command works afterwards — with editable GUI/CLI source available and auto-rebuild on git pull. gh is a convenience for the clone — substitute git clone https://github.com/eliharoun/agent-smith if you prefer.
Quick start
After installing, launch the companion agent and tell it what you want to build:
opencode --agent agent-smith # or: claude --agent agent-smith
"I want an agent that reviews TypeScript pull requests for type-safety issues."
The companion agent walks you through eight focused questions (identity, expertise, voice, targets, model, mode, permissions, skills), then scaffolds, validates, and installs the bundle. Or skip the conversation:
smith agent init my-debugger --from incident-debugger
smith agent install my-debugger
For the full installer behavior, paths, and recovery commands, see getting started.
What you can build
Four example bundles ship with the package. Install one in seconds with --from:
| Example | Mode | Permissions | Use it when... |
|---|---|---|---|
incident-debugger | subagent | read + edit + bash | a production incident is in progress and you want a partner that gathers signal, isolates root cause, and prefers rollback to forward-fix |
security-threat-modeler | primary | read-only | reviewing a new feature for STRIDE-style threats and producing a markdown threat model |
repo-cartographer | subagent | read-only + lsp | exploring an unfamiliar codebase: locating implementations, tracing call graphs, mapping module structure |
knowledge-demo | subagent | defaults | demonstrating knowledge sources end-to-end — inline budgeting and on-disk indexing |
smith agent init my-debugger --from incident-debugger
smith agent validate my-debugger
smith agent install my-debugger
Beyond the examples, anything you'd describe as a role with operational boundaries is a candidate: PR risk reviewers, AI-diff verifiers, support-ticket reproducers, release scribes, ADR stewards, migration surgeons. A general assistant can attempt any of these. A specialized agent does the same task repeatedly with the right persona, constraints, tools, and output format.
Agents vs skills
Skills and agents are different abstractions, not competitors. Most production setups use both.
- A skill is reusable know-how — a checklist, workflow, script bundle, or reference pack that any agent can load on demand. Portable across tools (Claude Code, OpenCode, Codex, and Kiro all consume the open Agent Skills standard) and lightweight (loaded only when relevant).
- A custom agent is a reusable worker identity — a role with its own persona, model tier, tool access, permissions, and isolated context window. Agents define who does the work; skills define how it should be done.
A pr-risk-reviewer works best as an agent: it should run read-only, examine the diff in its own context window so it doesn't pollute your main thread, route to a stronger reasoning model, and return a single merge recommendation. The review rubric it follows — severity definitions, output format, company conventions — is best authored as a skill the agent loads. The agent enforces the constraint; the skill encodes the procedure.
agent-smith manages the agent layer: portable 4-file bundles, validated against a strict schema, with permissions/model tier/skills declared in agent.config.json, installed correctly into Claude Code, OpenCode, Codex, and Kiro. Skills you author separately (or import from a shared catalog) plug into bundles via the skills field.
Browser GUI
If you'd rather click than type, smith gui launches a local browser interface that wraps every daily-workflow command — agent and skill management, knowledge sources, daemon control, doctor repair, update, jack-out, and persistent job history.
smith gui # default port 7777, auto-opens browser
For the developer setup (Vite dev server, Storybook, e2e), see gui/README.md.
Common commands
smith agent init <name> --from <example> # scaffold from a bundled example
smith agent validate # check every bundle against the schema
smith agent install <name> # render + install to its targets
smith agent install --from <git-url> # install from a git repo
smith agent install --from <archive.tgz> # install from an exported bundle archive
smith agent export <name> # package a bundle as a .smith-bundle.tgz
smith agent export <name> --format directory --to <dir>/ # publish into a catalog repo
smith agent install --from <local-dir> # install from a local checkout
smith agent list # all known agents and their targets
smith skill list # installed skills + drift status
smith skill install <catalog>/<name> # install a skill into all platforms
smith skill validate <name> # validate a skill's frontmatter
smith config get [key] # show model resolution settings
smith agent reconfigure <name> # grant/revoke refresh hooks for an agent
smith knowledge fetch <agent> [--source <id>] # refresh URL/git caches; --source for surgical per-source refresh
smith knowledge compile <agent> # offline re-derive compile-manifest from materialized files
smith knowledge wire <agent> # wire <agent>-knowledge MCP server into detected AI clients
smith knowledge unwire <agent> # remove that wiring
smith knowledge serve <agent> --stdio # stdio MCP server (BM25 search + range-bounded fetch)
smith knowledge remove <agent> <source-id> # remove a knowledge source from a bundle
smith doctor # platform health, schema drift, registry hygiene
smith status # registry + paths
smith update # upgrade agent-smith, any install type
# source checkout: git pull + bun install + doctor
# npm/bun/pnpm -g: runs the matching global upgrade
Full reference: smith --help, the cheat sheet, or the CLI reference.
Documentation
Start with the in-depth guide — a hub that links into focused topic spokes under guide/.
Getting started & authoring
01-getting-started.md— install layout, the first three commands, your first agent02-bundle-anatomy.md— what a bundle is, the four files, schema, validation, USER.md mechanics14-cli-reference.md— every command with every flag, exit codes, examples
Installing, models, and platforms
03-installing-and-rendering.md— whatsmith agent installdoes, per-platform output, idempotency06-permissions-and-platforms.md— capability mapping, presets, per-platform translator gaps, MCP servers07-models.md— model-tier resolution, per-platform behavior, curated fallbacks
Sharing, skills, and knowledge
05-skills.md— installing skills,requires.skills, skill catalogs, drift08-registries-and-catalogs.md— registries, catalog kinds, precedence04-knowledge.md— per-agent knowledge sources (files, dirs, URLs, git, Confluence, Jira), routing URL fetches through MCP servers, declaringmcp.required/mcp.peerbundle dependencies16-knowledge-compiler.md— v2 progressive disclosure:compileblock,agents-mdtarget, BM25 retrieval server, APM import15-sharing-and-distribution.md— end-to-end publisher + consumer flow, includingsmith agent exportto package a bundle as a.smith-bundle.tgzarchive
Operating and troubleshooting
09-daemon.md— what the daemon watches, lifecycle commands, debugging10-doctor.md— health-check sections, exit codes, drift remediation11-update-and-uninstall.md—smith update,smith agent uninstall,smith jack-out12-error-handling.md— exit-code taxonomy, everySmithErrorvariant13-paths-and-state.md— complete filesystem layout
Visual reference
ARCHITECTURE.md— component map, data flow, install lifecycle, glossaryCHEATSHEET.md— one-page command + paths + exit-code reference
Contributing
Pull requests welcome. See CONTRIBUTING.md for the tool-map / schema update workflow, local development setup, and release process.
bun install
bun test
bun run typecheck
To report a bug, open an issue. Security issues should be reported privately — see SECURITY.md.
By participating in this project you agree to abide by its Code of Conduct.
License
MIT — see LICENSE.