Drive CLI Agents

Use a CLI when you want its own login, tools, and local workflow.

pkg/agentpkg/aidisk · network

fig. 01 — Two places a CLI subprocess can sit

Both kinds run the same installed binary. The kind decides who owns the loop: the CLI, or pkg/agent.

When to reach for a CLI agent

• Use it when subscription pricing matters.
• Use it when the CLI already owns local tool policy.
• Use it when the provider-maintained loop is enough.
• Avoid it when you need pi-go tool execution.
• Avoid it when you need one portable provider API.

Run a CLI as the whole agent

c := catalog.New()
c.RegisterAgent("codex", codex.Factory(
  codex.WithWorkDir(workDir),
  codex.WithSandbox("read-only"),
  codex.WithApprovalPolicy("never"),
))

a, err := c.Agent("codex/gpt-5", agent.WithSystemPrompt("Answer about this repository."))

answer, err := agent.Prompt(ctx, a, "Summarize the package layout.")

The Codex CLI owns the agent loop. The pi-go agent interface still gives Run, Messages, and Close.

Run a CLI as a provider

provider := claudecli.New(
  claudecli.WithWorkDir(workDir),
  claudecli.WithModel("sonnet"),
)

model := ai.NewLanguageModel(ai.Model{ID: "sonnet", Name: "sonnet"}, provider)

a := agent.New(model, agent.WithSystemPrompt("Use short answers."))

The Claude CLI is only a language model here. The pi-go default loop still owns the tools and the turns.

Which CLIs support what

• claude runs as an agent, and claude-cli runs as a provider.
• codex runs as an agent, and codex-cli runs as a provider.
• cursor runs as an agent, and cursor-cli runs as a provider.
• antigravity runs as an agent, and antigravity-cli runs as a provider.
• The cmd/pi CLI registers these shortcuts for its own command.

Next: Provider Capability Matrix.