agentio is split into several Go modules so you only download what you use. Add the root module for the neutral types, then one module per agent you need: claude for Claude Code, codex for OpenAI Codex, builtin when you want every built-in agent at once. A program that only knows Claude Code never pulls the TOML or SQLite code Codex needs.
- Go 1.26.4 or newer (the
goline of every module). - A Go module of your own (
go mod init example.com/yourtool). - Nothing else: the library never needs the
claudeorcodexbinary to build, and reading a home needs only the files on disk.
Pick the modules from this table. Each row lists what it adds on top of the standard library.
| Module | Use it for | Pulls in |
|---|---|---|
github.com/ubgo/agentio |
neutral core: Agent, Spec, Host, Home, Target, Command, Token, errors, versions, enums, the typed capability accessors (agentio.UsageOf …) |
stdlib only |
github.com/ubgo/agentio/claude |
everything about Claude Code: install, homes, settings, hooks, MCP, account, usage, conversations, sessions, launch | root |
github.com/ubgo/agentio/codex |
everything about OpenAI Codex: install, config.toml, auth, usage, conversations, sessions, launch |
root, github.com/pelletier/go-toml/v2 |
github.com/ubgo/agentio/codex/state |
Codex's SQLite state index (state_5.sqlite) |
root, codex, modernc.org/sqlite |
github.com/ubgo/agentio/gemini |
everything about Gemini CLI: homes, install, settings, conversations, MCP, extensions, launch | root |
github.com/ubgo/agentio/pi |
everything about pi: agent dir, install, sessions, settings, trust, MCP, skills, launch | root |
github.com/ubgo/agentio/builtin |
every built-in agent in one call (builtin.New), plus agents described by config |
root, claude, codex, gemini, pi |
Claude Code only:
go get github.com/ubgo/agentio github.com/ubgo/agentio/claudeCodex only:
go get github.com/ubgo/agentio github.com/ubgo/agentio/codexEvery built-in agent, for a tool that loops over whatever is installed:
go get github.com/ubgo/agentio github.com/ubgo/agentio/builtinAdd github.com/ubgo/agentio/codex/state only when you read Codex's SQLite index; it is the one module with a large dependency (a pure-Go SQLite, no cgo).
The root module never imports a vendor module, and claude never imports codex, so the dependency graph stays exactly as the table shows.
Run the quick start from this repository to see the library work on a fixture home, with no real account, binary or network involved:
git clone https://github.com/ubgo/agentio
cd agentio/examples
go run ./quickstartIn your own module, build and vet after go get:
go build ./...
go vet ./...cd examples && go run ./quickstartThe first lines of the real output:
host: user=user PATH set=true
host: MODE=b EMPTY="" set=true MISSING set=false
install: path=$TMP/bin/claude
install: real=$TMP/lib/node_modules/@anthropic-ai/claude-code/cli.js
install: method=npm-global version=2.1.325
install: shadowed=$TMP/old/bin/claude
home: name=personal default=true dir=~/.claude
home: name=work default=false dir=~/.claude-work
neutral: id=claude name="Claude Code" binary=claude
$TMP is a temp dir holding a fake npm install and ~ is the fixture user home in claude/testdata/homes/2.1.325/userhome. Your first agent walks through the code.
- Importing
builtinpulls every vendor module. That is its job. A Claude-only tool should importclaudedirectly; it then never downloads go-toml or SQLite. codex/stateis separate fromcodexon purpose.codexreads rollout files andconfig.tomlwithout SQLite; only the state index needsmodernc.org/sqlite.- Vendor
ParseVersionhas the root shape.agentio.ParseVersion,claude.ParseVersionandcodex.ParseVersionall return(agentio.Version, bool);okis false when the text holds no version. See Versions. - Building never runs the vendor CLI. No step here needs
claudeorcodexon PATH; when they are missing,Installreturns an error matchingagentio.ErrNotInstalledrather than failing to build.
- Your first agent — the quick start, step by step
- Host: the only door to the machine
- Built-in agents
- Choosing guides
- Feature index