Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@ agentkit-loop = { version = "=0.10.13", features = ["otel"] }
agentkit-mcp = "=0.11.2"
agentkit-http = "=0.10.7"
agentkit-plugins = "=0.10.7"
agentkit-provider-anthropic = "=0.10.11"
agentkit-provider-openai = "=0.10.13"
agentkit-provider-openrouter = "=0.10.8"
agentkit-task-manager = "=0.10.7"
Expand Down
7 changes: 6 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ Fewer model round trips repeat less context and complete more work in each reque
- **Reusable subagents.** A subagent is a reusable value. You can continue, fork, inspect, and close a subagent. You can require JSON that matches a schema. You can also use Claude Code, Codex, Cursor, or Kit as the subagent harness over ACP.
- **Open protocols.** Kit supports ACP v1 and v2 over stdio, HTTP/SSE, and WebSocket. Kit supports A2A v1 in both directions. It also supports MCP, Agent Skills, and Agent Plugin packages.
- **Long sessions.** Kit synchronizes each append-only JSONL transcript item to disk before it accepts the item. It compacts context automatically at 80% of the context window. You can resume a session from `tui`, `prompt`, or any ACP client. Kit also uses crash-safe locks. It retries eligible `openai-subscription` failures for up to 24 hours.
- **Model choice.** Kit supports ChatGPT subscriptions through native OAuth. It also supports models through OpenRouter and the Speakeasy AI Control Plane. Use `/model` to change the model during a session.
- **Model choice.** Kit supports ChatGPT subscriptions through native OAuth. It also supports the Anthropic API directly and models through OpenRouter and the Speakeasy AI Control Plane. Use `/model` to change the model during a session.
- **Small runtime.** Kit has no permissions framework, sandbox, or web UI. The `--root` option sets the working directory. Kit is a runtime, not a security boundary. Run Kit inside a security boundary that you trust. See the [trust model](docs/user/security-limits-and-troubleshooting.md).

## Install
Expand Down Expand Up @@ -165,6 +165,11 @@ kit serve --root /path/to/project --remote-acp --no-a2a --no-stdio --http 0.0.0.

OpenRouter and Speakeasy use the same login process. Run `kit auth login openrouter` or `kit auth login speakeasy`. Then add `--provider openrouter --model anthropic/claude-sonnet-5` to the Kit command that you run. Providers and MCP servers share one credential backend (`--credential-store keychain|file|memory`).

For direct Anthropic API usage, run `kit auth login anthropic`, then select
`--provider anthropic --model claude-sonnet-5-5`. Use a single-workspace Console
API key; `ANTHROPIC_API_KEY` is also supported. See
[Anthropic setup](docs/user/getting-started-and-configuration.md#direct-anthropic-api).

### Coming from Claude Code or Codex

Read [Migrate from Claude Code or Codex](docs/user/migrating-from-claude-code-and-codex.md) for the file mappings, safety boundaries, and settings that need manual review. Or start `kit tui` in the existing project and paste this prompt:
Expand Down
37 changes: 34 additions & 3 deletions docs/user/getting-started-and-configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ tarball with the full feature set, not a static musl tarball.

## Choose a provider and authenticate

Kit supports `openai-subscription`, `openrouter`, and `speakeasy`. The default provider is `openai-subscription`, and the default model is `gpt-5.4`. A `--provider` or `--model` command-line value overrides the corresponding value in `~/.kit/config.toml`.
Kit supports `openai-subscription`, `anthropic`, `openrouter`, and `speakeasy`. The default provider is `openai-subscription`, and the default model is `gpt-5.4`. A `--provider` or `--model` command-line value overrides the corresponding value in `~/.kit/config.toml`.

### ChatGPT subscription with native OpenAI login

Expand Down Expand Up @@ -70,6 +70,37 @@ Use `kit auth status openai` to check the credential.
the local credential if revocation fails. `kit auth logout openai --local-only`
skips revocation and prints a warning.

### Direct Anthropic API

Use a **single-workspace API key** from [Claude Console](https://platform.claude.com/settings/keys).
Kit uses the Anthropic API directly, not Claude Max subscription OAuth:

```sh
kit auth login anthropic --credential-store keychain
kit auth status anthropic --credential-store keychain
kit prompt --provider anthropic --model claude-sonnet-5-5 \
--credential-store keychain "Summarize this project"
kit auth logout anthropic --credential-store keychain
```

Login reads the key at a hidden prompt, validates it with the non-inference Models
API, and saves it only on success. Use the same persistent credential store for
login and runtime commands. File storage is also supported with
`--credential-store file --credential-dir /path/to/private-directory`.
Alternatively, set `ANTHROPIC_API_KEY`; a nonempty environment key overrides the
saved key. Do not put API keys in command-line arguments or `config.toml`.
Multi-workspace keys that require an explicit workspace header are not supported.

Use direct Anthropic model IDs with `--model`, not OpenRouter's
`anthropic/…` IDs. Kit discovers available models, context limits, and thinking
capabilities from the authenticated Anthropic Models API rather than a fixed
model list. If discovery is unavailable, an explicitly selected model remains
usable with default reasoning; Kit does not guess its context limit. Responses
have an output limit of at most 16,384 tokens, capped by the model's advertised
maximum when available. Leave `reasoning_effort` unset for the provider default,
or select `low`, `medium`, or `high` when discovery confirms support. Logout deletes the locally
saved key; revoke it in Claude Console to disable it remotely. An environment key remains active after logout.

### OpenRouter API key and model

Set `OPENROUTER_API_KEY`, select `openrouter`, and use an OpenRouter model identifier:
Expand Down Expand Up @@ -286,7 +317,7 @@ subdir = "agent-plugins/example"

`root`, `provider`, `model`, and credential settings apply to all four runtime commands. Subagent model aliases and explicit-override allowlists are scoped by fully qualified harness under `[subagent.harnesses."acp.name"]`. Omitting `allow_model_overrides` permits all explicit model selections accepted by that harness; an empty list disables explicit model overrides. This policy does not restrict the harness's inherited or default model.

`a2a` applies to `serve` and `tui`. Configured plugins can provide MCP servers without `mcp_config`; supported `stdio` and `streamable-http` declarations are registered, while `sse` declarations are skipped with a stderr diagnostic. MCP servers merge by name in this order: plugins, configured `mcp_config`, `<canonical-root>/.mcp.json`, then `--mcp-config`. Higher layers replace whole conflicts while preserving non-conflicting lower entries; live removal reveals the next lower layer. Plugin data is stored under `<config-directory>/plugin-data/<plugin-manifest-name>`. See [Agent Plugins](agent-plugins.md) for placeholders, collision rules, and ACP child behavior. `otel_endpoint` enables OTLP export of AgentKit's GenAI trace spans. `otel_protocol` accepts exactly `grpc`, `http/protobuf`, or `http/json`; gRPC is the default. For either HTTP protocol, Kit appends `/v1/traces` to a base endpoint unless it already ends with that path. `credential_store` selects one backend for OpenAI, Speakeasy, and MCP and defaults to `memory`; selecting `file` requires `credential_dir`, while a credential directory is invalid with `memory` or `keychain`. Memory credentials are process-local and are not shared with the TUI server process or nested Kit children. Standalone OpenAI and Speakeasy login requires persistent `keychain` or `file` storage. ACP profiles are direct executable-and-argument configurations, not shell command strings. `[subagent].harness` must name an available fully qualified profile such as `acp.review`; otherwise startup reports `unknown subagent ACP harness`. When no subagent harness is selected, the built-in `acp.kit` profile is used.
`a2a` applies to `serve` and `tui`. Configured plugins can provide MCP servers without `mcp_config`; supported `stdio` and `streamable-http` declarations are registered, while `sse` declarations are skipped with a stderr diagnostic. MCP servers merge by name in this order: plugins, configured `mcp_config`, `<canonical-root>/.mcp.json`, then `--mcp-config`. Higher layers replace whole conflicts while preserving non-conflicting lower entries; live removal reveals the next lower layer. Plugin data is stored under `<config-directory>/plugin-data/<plugin-manifest-name>`. See [Agent Plugins](agent-plugins.md) for placeholders, collision rules, and ACP child behavior. `otel_endpoint` enables OTLP export of AgentKit's GenAI trace spans. `otel_protocol` accepts exactly `grpc`, `http/protobuf`, or `http/json`; gRPC is the default. For either HTTP protocol, Kit appends `/v1/traces` to a base endpoint unless it already ends with that path. `credential_store` selects one backend for model providers and MCP and defaults to `memory`; selecting `file` requires `credential_dir`, while a credential directory is invalid with `memory` or `keychain`. Memory credentials are process-local and are not shared with the TUI server process or nested Kit children. Standalone provider login requires persistent `keychain` or `file` storage. ACP profiles are direct executable-and-argument configurations, not shell command strings. `[subagent].harness` must name an available fully qualified profile such as `acp.review`; otherwise startup reports `unknown subagent ACP harness`. When no subagent harness is selected, the built-in `acp.kit` profile is used.

Agent hooks are configured in `~/.agents/hooks.json` and `<root>/.agents/hooks.json`. See [Agent Hooks Protocol](agent-hooks-protocol.md).

Expand Down Expand Up @@ -376,7 +407,7 @@ The hidden-tool catalog is captured when Kit creates the session's compose sourc

## Troubleshoot startup and configuration

- **`invalid config ...`**: validate known values and TOML types. Unknown fields are ignored; provider values are exactly `openai-subscription`, `openrouter`, and `speakeasy`, and credential-store values are `memory`, `keychain`, and `file`.
- **`invalid config ...`**: validate known values and TOML types. Unknown fields are ignored; provider values are exactly `openai-subscription`, `anthropic`, `openrouter`, and `speakeasy`, and credential-store values are `memory`, `keychain`, and `file`.
- **`could not read config ...`**: check permissions and that `$HOME/.kit/config.toml` is a readable regular file. Deleting an unwanted config is valid because a missing file falls back to defaults.
- **`credential_dir is required when credential_store is file`**: add the directory or choose another store.
- **`credential_dir requires credential_store to be file`**: remove the directory or select `file`.
Expand Down
2 changes: 2 additions & 0 deletions docs/user/provider-usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ kit usage openrouter --credential-store keychain
```

Supported providers are `openai` (also `openai-subscription`) and `openrouter`.
Direct Anthropic API credit balances are not available through `kit usage`; check
Billing in Claude Console.
Omit the provider to check authenticated supported providers. The command uses the effective
credential storage from configuration and CLI overrides (`--credential-store` and
`--credential-dir`). OpenRouter also uses the effective `--openrouter-api-key` or
Expand Down
2 changes: 1 addition & 1 deletion docs/user/tui-and-sessions.md
Original file line number Diff line number Diff line change
Expand Up @@ -191,7 +191,7 @@ The TUI handles `/new`, `/resume`, `/sessions`, `/close`, `/model`, `/effort`, `

The other commands listed above are available only while the session is idle. `/agents` toggles the agent roster without starting a model turn. `/new` closes the current session and starts a fresh persisted session. It clears the visible transcript but does not delete or alter the previous session, which remains resumable by its ID. Text following `/new` becomes the new session's first prompt. `/resume <session-id>` closes the current session, resumes the requested durable session, and replays its transcript; selecting the already-active ID is a no-op. `/sessions` opens a visible newest-first selector for the same workspace. Up and Down move, Enter uses the existing resume flow, `R` opens an inline rename field, and Esc cancels renaming or closes the dialog. Submit an empty rename and confirm to clear the custom name. After a save, the picker remains open on the selected session and refreshes its displayed name. `/close` closes the current session and exits the TUI.

`/model` opens the model selector. `/effort` opens the advertised ACP reasoning-effort selector; `/effort default|low|medium|high` selects directly. In either dialog, Tab toggles saving the selection to `~/.kit/config.toml`, Enter selects, and Esc closes. Saving `default` removes top-level `reasoning_effort`; other values update it without replacing unrelated TOML. New sessions start from the resolved CLI/TOML default. Durable sessions remember their reasoning-effort selection, including an explicit provider `default`, and restore it on load or resume even if the process default has changed. Older transcripts without a recorded effort continue to use the process default. Forks inherit the source session’s current effort. Saving to TOML changes the default for future sessions; it is not required to retain the effort of the current session. Model selection still starts from the resolved CLI/TOML default on reload. Reasoning-effort records require a Kit version that understands transcript schema 6; older versions reject these records rather than silently discard the saved selection.
`/model` opens the model selector on a provider list; Enter on a provider shows that provider's models. Typing searches only the current page, and the search clears when you move between pages. Esc returns from the model list to the provider list, and closes the selector from the provider list. `/effort` opens the advertised ACP reasoning-effort selector; `/effort default|low|medium|high` selects directly. In either dialog, Tab toggles saving the selection to `~/.kit/config.toml`, Enter selects, and Esc closes. Saving `default` removes top-level `reasoning_effort`; other values update it without replacing unrelated TOML. New sessions start from the resolved CLI/TOML default. Durable sessions remember their reasoning-effort selection, including an explicit provider `default`, and restore it on load or resume even if the process default has changed. Older transcripts without a recorded effort continue to use the process default. Forks inherit the source session’s current effort. Saving to TOML changes the default for future sessions; it is not required to retain the effort of the current session. Model selection still starts from the resolved CLI/TOML default on reload. Reasoning-effort records require a Kit version that understands transcript schema 6; older versions reject these records rather than silently discard the saved selection.

Before changing models, Kit compares the latest provider-reported transcript occupancy with the target model's advertised context window. It adds a 20% tokenizer margin (`ceil(tokens × 1.20)`) and warns when that estimate is at least 80% of the target window. This is the latest request's occupancy, not accumulated session usage; cached input tokens are not counted twice.

Expand Down
Loading
Loading