Skip to content

Commit 305d55f

Browse files
jkyberneeesjkyberneees
committed
docs: split README into focused sub-docs, add sessions docs
BREAKDOWN: README.md → compact entry point with overview + links to docs/ docs/CLI.md → full CLI reference (commands, flags, examples) docs/CONFIG.md → config files, env vars, priority chain, kode init docs/PROVIDERS.md → models, profiles, thinking levels, context window docs/SESSIONS.md → multi-turn sessions (new: --session, continue, session list/show/delete/trim/cleanup) docs/SECURITY.md → prompt injection defense, sandbox security docs/DEVELOPMENT.md → source layout, testing, building, contributing docs/SANDBOXING.md → moved from root (updated ref paths) Also updated kode init output: docs/SANDBOXING.md instead of SANDBOXING.md.
1 parent 3c96b6a commit 305d55f

9 files changed

Lines changed: 667 additions & 676 deletions

File tree

‎README.md‎

Lines changed: 51 additions & 641 deletions
Large diffs are not rendered by default.

‎cmd/kode/main.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -374,7 +374,7 @@ func initConfig(args []string) error {
374374
fmt.Println(" sandbox_env Extra env vars (object)")
375375
fmt.Println(" sandbox_volumes Extra volume mounts (array)")
376376
fmt.Println()
377-
fmt.Println(" See SANDBOXING.md for full sandbox documentation.")
377+
fmt.Println(" See docs/SANDBOXING.md for full sandbox documentation.")
378378
fmt.Println(" Priority: config file < KODE_* env < CLI flags")
379379
return nil
380380
}

‎docs/CLI.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# CLI Reference
2+
3+
## Commands
4+
5+
| Command | Description |
6+
|---------|-------------|
7+
| `kode run [flags] <task>` | Execute a task with the agent loop (single-shot by default) |
8+
| `kode run --session [flags] <task>` | Execute and save conversation as a multi-turn session |
9+
| `kode continue [--id <id>] <task>` | Continue the most recent session (or by `--id`) |
10+
| `kode session list` | List sessions |
11+
| `kode session show [id]` | Show session details (default: latest) |
12+
| `kode session delete <id>` | Delete a session |
13+
| `kode session trim <id> <n>` | Keep only the `n` most recent messages |
14+
| `kode session cleanup <days>` | Delete sessions older than N days |
15+
| `kode init [--global] [--force]` | Create a config file template |
16+
| `kode version` | Print version and exit |
17+
18+
## Run flags
19+
20+
| Flag | Type | Default | Description |
21+
|------|------|---------|-------------|
22+
| `--model <name>` | string | `deepseek-chat` | LLM model — profiles auto-set thinking/timeout (see [Providers](docs/PROVIDERS.md)) |
23+
| `--base-url <url>` | string | `https://api.deepseek.com/v1` | OpenAI-compatible API endpoint |
24+
| `--max-iter <n>` | int | `90` | Max think→act cycles |
25+
| `--thinking <level>` | string | profile default | Reasoning depth: `enabled`/`disabled`/`low`/`medium`/`high` |
26+
| `--sandbox` | bool | false | Execute shell commands inside Docker container |
27+
| `--no-color` | bool | false | Disable colored terminal output |
28+
| `--no-agents` | bool | false | Skip loading AGENTS.md |
29+
| `--session` | bool | false | Save conversation as a multi-turn session |
30+
| `--system <prompt>` | string | built-in | Override system prompt |
31+
32+
## Sandbox flags
33+
34+
| Flag | Default | Description |
35+
|------|---------|-------------|
36+
| `--sandbox-image <img>` | `alpine:latest` | Docker image |
37+
| `--sandbox-network <mode>` | `bridge` | Network: `bridge`/`none`/`host` |
38+
| `--sandbox-readonly` | false | Mount working directory read-only |
39+
| `--sandbox-memory <s>` | — | Memory limit (e.g. `512m`, `2g`) |
40+
| `--sandbox-cpus <n>` | — | CPU limit (e.g. `0.5`, `2`) |
41+
| `--sandbox-user <s>` | — | Run as user (`uid:gid`) |
42+
43+
## Init flags
44+
45+
| Flag | Description |
46+
|------|-------------|
47+
| `--global`, `-g` | Create global config at `~/kode/config.json` |
48+
| `--force`, `-f` | Overwrite existing file without prompting |
49+
50+
## Examples
51+
52+
```bash
53+
# Quick task (single-shot, no session saved)
54+
kode run "How many Go files in this project?"
55+
56+
# Save as session for follow-up
57+
kode run --session "Refactor the auth module"
58+
59+
# Continue a session
60+
kode continue "Now add error handling to the refactored auth"
61+
62+
# Continue a specific session by ID
63+
kode continue --id 20260518-abc123 "Add unit tests"
64+
65+
# List all sessions
66+
kode session list
67+
68+
# Show latest session transcript
69+
kode session show
70+
71+
# Show a specific session
72+
kode session show 20260518-abc123
73+
74+
# Trim session to last 10 messages (preserves system prompt)
75+
kode session trim 20260518-abc123 10
76+
77+
# Delete sessions older than 30 days
78+
kode session cleanup 30
79+
80+
# Wipe all sessions
81+
kode session cleanup 0
82+
83+
# OpenAI
84+
kode run --model gpt-4o --base-url https://api.openai.com/v1 "Explain this code"
85+
86+
# Sandboxed execution
87+
kode run --sandbox "npm test"
88+
89+
# Custom sandbox image
90+
kode run --sandbox --sandbox-image node:20-alpine "node --version"
91+
92+
# Custom system prompt
93+
kode run --system "You are a Go expert. Answer with code only." "Write HTTP server"
94+
```
95+
96+
## Config priority
97+
98+
Config sources from lowest to highest priority:
99+
100+
```
101+
1. ~/kode/config.json ← Global defaults
102+
2. ./kode.json ← Project overrides
103+
3. KODE_* env vars ← Runtime overrides
104+
4. CLI flags ← Explicit invocation (highest)
105+
```
106+
107+
See [Configuration](CONFIG.md) for details.

‎docs/CONFIG.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# Configuration
2+
3+
kode uses a **layered configuration system** with convention over configuration — opt-in files and environment variables, no mandatory setup.
4+
5+
## Priority chain
6+
7+
Each layer overrides the one below it. Unset fields inherit from the layer below:
8+
9+
```
10+
1. ~/kode/config.json ← Global defaults (shared across projects)
11+
2. ./kode.json ← Project-specific overrides
12+
3. KODE_* env vars ← Runtime/environment overrides
13+
4. CLI flags ← Explicit invocation (highest priority)
14+
```
15+
16+
## Config files
17+
18+
### Global defaults (`~/kode/config.json`)
19+
20+
Shared across all projects:
21+
22+
```json
23+
{
24+
"model": "deepseek-v4-flash",
25+
"base_url": "https://api.deepseek.com/v1",
26+
"api_key": "${DEEPSEEK_API_KEY}",
27+
"thinking": "",
28+
"max_iterations": 90,
29+
"sandbox": false,
30+
"no_color": false,
31+
"no_agents": false,
32+
"system": ""
33+
}
34+
```
35+
36+
### Project overrides (`./kode.json`)
37+
38+
Same schema as global. Only set the fields you want to override:
39+
40+
```json
41+
{
42+
"model": "gpt-4o",
43+
"base_url": "https://api.openai.com/v1",
44+
"max_iterations": 30
45+
}
46+
```
47+
48+
Both files are optional. Missing files are silently ignored. String values support `${VAR}` environment variable substitution — useful for API keys without plaintext storage.
49+
50+
## Environment variables
51+
52+
Every config knob has a `KODE_*` counterpart:
53+
54+
| Variable | Maps to | Type |
55+
|----------|---------|------|
56+
| `KODE_MODEL` | `--model` | string |
57+
| `KODE_BASE_URL` | `--base-url` | string |
58+
| `KODE_API_KEY` | config files only | string |
59+
| `KODE_THINKING` | `--thinking` | string |
60+
| `KODE_MAX_ITER` | `--max-iter` | int |
61+
| `KODE_SANDBOX` | `--sandbox` | bool |
62+
| `KODE_NO_COLOR` | `--no-color` | bool |
63+
| `KODE_NO_AGENTS` | `--no-agents` | bool |
64+
| `KODE_SYSTEM` | `--system` | string |
65+
| `KODE_SANDBOX_IMAGE` | `--sandbox-image` | string |
66+
| `KODE_SANDBOX_NETWORK` | `--sandbox-network` | string |
67+
| `KODE_SANDBOX_READONLY` | `--sandbox-readonly` | bool |
68+
| `KODE_SANDBOX_MEMORY` | `--sandbox-memory` | string |
69+
| `KODE_SANDBOX_CPUS` | `--sandbox-cpus` | string |
70+
| `KODE_SANDBOX_USER` | `--sandbox-user` | string |
71+
72+
## API key fallback order
73+
74+
`KODE_API_KEY` → `DEEPSEEK_API_KEY` → `OPENAI_API_KEY`
75+
76+
## kode init
77+
78+
Create a config file template:
79+
80+
```bash
81+
# Local project config (./kode.json)
82+
kode init
83+
84+
# Global config (~/kode/config.json)
85+
kode init --global
86+
87+
# Overwrite existing file
88+
kode init --force
89+
```
90+
91+
## Quick examples
92+
93+
```bash
94+
# Global config
95+
echo '{"api_key": "${DEEPSEEK_API_KEY}", "model": "deepseek-v4-flash"}' > ~/kode/config.json
96+
kode run "list files"
97+
98+
# Per-project override
99+
echo '{"max_iterations": 30}' > ./kode.json
100+
kode run "quick status"
101+
102+
# Env var override for one-off
103+
KODE_SANDBOX=true kode run "run untrusted script"
104+
105+
# CLI flag always wins
106+
kode run --model gpt-4o --base-url https://api.openai.com/v1 "task"
107+
```

‎docs/DEVELOPMENT.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Development
2+
3+
## Prerequisites
4+
5+
- Go 1.24+
6+
- Docker (for sandbox integration tests only)
7+
8+
## Building
9+
10+
```bash
11+
go build -o kode ./cmd/kode
12+
```
13+
14+
## Testing
15+
16+
```bash
17+
# All tests
18+
go test ./... -v -count=1
19+
20+
# Specific package
21+
go test ./internal/session/ -v
22+
```
23+
24+
Zero external test dependencies — tests use `httptest`, `testing`, and the standard library only.
25+
26+
### Test coverage
27+
28+
| Package | Tests | Focus |
29+
|---------|-------|-------|
30+
| `kode` | 31 | Config defaults, API key fallback, thinking passthrough, model profiles, AGENTS.md |
31+
| `internal/config` | 17 | Config file loading, env vars, merge chain, var expansion |
32+
| `internal/llm` | 18 | JSON marshaling, thinking fields, response parsing, usage statistics |
33+
| `internal/loop` | 7 | ReAct engine with httptest mock server |
34+
| `internal/session` | 19 | CRUD, trim, cleanup, list, latest, edge cases |
35+
| `internal/tool` | 7 | Registry CRUD, lookup, duplicate detection |
36+
| `cmd/kode` | 20+ | Flag parsing, init, version, sandbox setup, integration |
37+
38+
## Source layout
39+
40+
```
41+
kode.go Public API (Config, New, Run, Close)
42+
kode_test.go Config and model profile tests
43+
internal/
44+
config/
45+
loader.go Config file loading, env vars, priority merge
46+
loader_test.go Config loading tests
47+
llm/
48+
client.go OpenAI-compatible HTTP client
49+
client_test.go JSON marshaling + response parsing tests
50+
loop/
51+
loop.go ReAct engine (observe → think → act → repeat)
52+
loop_test.go Engine tests with mock server
53+
session/
54+
session.go Session store (CRUD, trim, cleanup)
55+
session_test.go Session tests
56+
render/
57+
render.go Terminal output with model label and color
58+
tool/
59+
registry.go Thread-safe tool registry
60+
registry_test.go Registry tests
61+
cmd/kode/
62+
main.go CLI entry point, flag parsing, commands, sandbox
63+
main_test.go CLI tests
64+
shell.go Built-in shell tool (local or docker exec)
65+
shell_test.go Shell + sandbox tests
66+
docs/ Documentation
67+
CLI.md CLI reference
68+
CONFIG.md Configuration system
69+
PROVIDERS.md Models, profiles, thinking, context
70+
SESSIONS.md Multi-turn sessions
71+
SECURITY.md Prompt injection, security model
72+
SANDBOXING.md Sandbox configuration
73+
DEVELOPMENT.md This file
74+
```
75+
76+
## Contributing
77+
78+
1. Fork and clone
79+
2. Make changes
80+
3. Run `go test ./...`
81+
4. Open a PR
82+
83+
**Zero-dependency policy:** Contributions must not introduce external Go modules. stdlib only.

0 commit comments

Comments
 (0)