Documentation
¶
Overview ¶
Package agentadapter provides a unified abstraction for injecting the agnt system prompt into AI coding agents.
Historically, cmd/agnt/run.go and cmd/agnt/run_windows.go both carried hardcoded special-cases: Claude Code received the prompt via the `--append-system-prompt` flag, while every other known agent (gemini, copilot, aider, cursor, cursor-agent, opencode, kimi, kimi-cli, auggie) received it as initial stdin text 500ms after launch. The list and the per-agent strategy were duplicated across the unix and windows entrypoints, and there was no way for a project to override behavior per-agent.
This package centralizes that logic. An Adapter captures the knowledge of how to recognize a given AI CLI and how to hand it the agnt system prompt. The built-in registry (Registry) ships the same set of agents the old hardcoded lists supported, preserving behavior. New agents are added by registering a new Adapter; per-agent overrides (custom flag name, stdin delay, or disabling injection entirely) come from the `ai.adapters` block in `.agnt.kdl`.
Index ¶
Constants ¶
const DefaultStdinDelay = 500 * time.Millisecond
DefaultStdinDelay is the delay between agent launch and setup-mode stdin prompt delivery for stdin-capable adapters.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Adapter ¶
type Adapter interface {
// Name returns the canonical lowercase identifier for the agent
// (e.g. "claude", "gemini"). Used for config lookups and logging.
Name() string
// Matches reports whether the given command invokes this agent.
// Implementations must handle bare names ("claude"), absolute paths
// ("/usr/bin/claude"), relative paths ("./aider"), and — on Windows —
// .exe suffixes. Matching is case-insensitive on the base name.
Matches(command string) bool
// BuildArgs returns the argv to use when launching the agent. For
// flag-based adapters it appends the injection flag and prompt; for
// stdin-based adapters it returns baseArgs unchanged. The returned
// slice must not alias baseArgs — callers may further mutate it.
BuildArgs(baseArgs []string, prompt string) []string
// InitialStdin returns the bytes to write to the child's stdin after
// StdinDelay has elapsed. Returns nil for flag-based adapters or
// when prompt is empty.
InitialStdin(prompt string) []byte
// StdinDelay is how long to wait after launch before writing the
// InitialStdin bytes. Ignored for flag-based adapters.
StdinDelay() time.Duration
}
Adapter describes how to recognize a specific AI coding agent and how to hand it the agnt system prompt.
Implementations must be safe for concurrent use and must not mutate the inputs they receive. Two injection strategies are supported:
- Flag-based: BuildArgs returns a modified argv; InitialStdin returns nil. Example: Claude Code (--append-system-prompt).
- Stdin-capable: BuildArgs returns baseArgs unchanged; InitialStdin returns the bytes to write to the child's stdin after StdinDelay has elapsed when the caller chooses stdin delivery (setup mode). Example: gemini, aider, cursor, etc.
An adapter may return an empty argv change and nil stdin if the prompt is empty — callers must tolerate nil/empty returns without injecting anything.
func Universal ¶ added in v0.13.26
Universal returns a stdin-based adapter for an unrecognized command, so any tool launched under `agnt run` still receives the agnt prompt (via stdin after the default delay) rather than silently getting nothing. The verb, not the agent identity, decides that injection happens; this is the fallback when Registry.Lookup finds no registered match. The adapter's name is derived from the command's base name for logging.
type KimiOptions ¶ added in v0.12.46
type KimiOptions struct {
// Transport selects the MCP transport mode. Empty means kimi uses
// its default (command). Valid values: "command", "sse", "streamable".
Transport KimiTransportMode
// ExtraArgs are additional flags passed verbatim before any
// injection flags. Useful for --config, --mcp, --verbose, --debug.
ExtraArgs []string
}
KimiOptions configures a kimi adapter beyond the defaults.
type KimiTransportMode ¶ added in v0.12.46
type KimiTransportMode string
KimiTransportMode names the MCP transport modes kimi-cli supports.
const ( // KimiTransportCommand is the default local-executable transport. KimiTransportCommand KimiTransportMode = "command" // KimiTransportSSE is the server-sent events over HTTP transport. KimiTransportSSE KimiTransportMode = "sse" // KimiTransportStreamable is the streamable HTTP transport. KimiTransportStreamable KimiTransportMode = "streamable" )
type Override ¶
type Override struct {
// Disabled, when true, disables prompt injection for this agent
// entirely — the adapter's BuildArgs returns baseArgs unchanged and
// InitialStdin returns nil.
Disabled bool
// FlagName overrides the CLI flag used for flag-based injection
// (e.g. "--system-prompt" instead of "--append-system-prompt").
// Empty means "use the adapter default". Ignored by stdin-based
// adapters.
FlagName string
// StdinDelay overrides the delay before injecting stdin. Zero means
// "use the adapter default". Ignored by flag-based adapters.
StdinDelay time.Duration
// Aliases are extra command base names that resolve to this adapter.
// They let a project map an opaque wrapper / shell-alias target (e.g.
// "cdsp") onto a known agent ("claude") so it gets the right injection
// mechanism instead of falling through to the universal stdin adapter.
Aliases []string
}
Override captures per-agent configuration overrides, typically sourced from the `ai.adapters` block in `.agnt.kdl`. Zero values mean "inherit the adapter's default".
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry holds a set of Adapter instances and resolves a command string to the first matching adapter. It also applies per-adapter overrides supplied via configuration.
The zero value is not usable — construct one via NewRegistry or DefaultRegistry.
func DefaultRegistry ¶
func DefaultRegistry() *Registry
DefaultRegistry returns a registry pre-populated with all agents the legacy run.go / run_windows.go code supported. Order matters: Claude is checked first because its name is a proper substring of no other agent, but placing it first keeps lookup cheap for the common case.
func NewRegistry ¶
func NewRegistry() *Registry
NewRegistry creates an empty registry with no adapters registered. Prefer DefaultRegistry for normal usage.
func (*Registry) Lookup ¶
Lookup finds the first adapter whose Matches returns true for the given command. Returns nil when no adapter matches. The returned adapter reflects any configured overrides for that agent.
func (*Registry) Register ¶
Register adds an adapter to the registry. Adapters are consulted in registration order during Registry.Lookup.
func (*Registry) SetOverrides ¶
SetOverrides replaces the per-adapter override map. Keys are adapter names (matched against Adapter.Name); unknown keys are ignored. Passing nil clears all overrides.