Skip to content

Commit e84ac26

Browse files
jkyberneeesjkyberneees
committed
docs: strategic README redesign with features, cheatsheet, and full doc index
1 parent 16704a6 commit e84ac26

1 file changed

Lines changed: 132 additions & 116 deletions

File tree

‎README.md‎

Lines changed: 132 additions & 116 deletions
Original file line numberDiff line numberDiff line change
@@ -1,166 +1,182 @@
11
# kode
22

3-
The fastest, minimal, zero-dependency Go autonomous agent runtime.
3+
**The fastest, minimal, zero-dependency Go autonomous agent runtime.**
44

5-
`kode` runs the ReAct (Reasoning + Acting) loop — "think, therefore act" — as a single binary. No frameworks, no SDKs, no Python venvs. Just one loop and your tools.
5+
One binary. One loop. Zero frameworks. ReAct (Reasoning + Acting) — think, therefore act.
66

77
```bash
8+
# Install
9+
go install github.com/BackendStack21/kode/cmd/kode@latest
10+
11+
# Use
12+
export DEEPSEEK_API_KEY=sk-...
813
kode run "How many lines in go.mod?"
914
# → 3 lines
10-
11-
kode run "Fix the OOM bug in default-hooks.js"
12-
# → [reads file, edits code, runs tests, reports result]
1315
```
1416

15-
## Design
17+
---
1618

17-
- **Zero deps** — `net/http`, `encoding/json`, `context`. That's it.
18-
- **LLM-agnostic** — Any OpenAI-compatible endpoint (Deepseek, OpenAI, Ollama, vLLM...)
19-
- **Tool-first** — Tools are the only extension point. No chains, no prompts.
20-
- **Sandbox-ready** — `kode run --sandbox` → isolated Docker container, destroyed on exit
21-
- **Single binary** — `go build` → one file. Drop it anywhere.
22-
- **Multi-turn** — `kode run --session` and `kode continue` for persistent conversations
23-
- **Configurable** — 4-layer config (global → project → env → CLI), `${VAR}` substitution
24-
- **Skills system** — On-demand knowledge through trigger‑matched SKILL.md files. Auto‑learn patterns with `--learn`. Import skills from URIs with LLM risk assessment.
25-
- **Persistent memory** — Three‑tier memory system (facts + session buffer + episode search). Agent‑managed via `memory` tool. Merge‑on‑write with go‑vector similarity detection saves ~80% LLM calls.
19+
## Why kode
2620

27-
## Install
21+
kode is not a framework. It's a **runtime** — the smallest possible surface area between an LLM and your tools.
2822

29-
### go install (recommended)
23+
| | kode | Python agents (LangChain, CrewAI, etc.) |
24+
|---|---|---|
25+
| Dependencies | **Zero.** stdlib only | 200+ packages |
26+
| Binary size | ~5 MB static | 50-200 MB with venv |
27+
| Startup | **Instant** | 2-10s (Python imports) |
28+
| Sandbox | `--sandbox` flag | Requires manual Docker setup |
29+
| Tool interface | One interface, one method | Class hierarchies + decorators |
3030

31-
```bash
32-
go install github.com/BackendStack21/kode/cmd/kode@latest
33-
```
31+
---
3432

35-
### From source
33+
## Strategic Features
3634

37-
```bash
38-
git clone https://github.com/BackendStack21/kode.git
39-
cd kode
40-
go build -o kode ./cmd/kode
41-
```
35+
### 🔒 Sandboxed Execution
36+
`kode run --sandbox` — every session spawns an isolated Docker container. No network, no host mounts beyond the working directory, zero capabilities, destroyed on exit. Full security model in [docs/SANDBOXING.md](docs/SANDBOXING.md).
4237

43-
### Binary download
38+
### 🧩 Sub-Agent Delegation
39+
Parallel OS-process sub-agents via `delegate_tasks`. True isolation — each sub-agent is a fresh `kode subagent` process with its own config, tools, and termination timeout. Up to 8 concurrent workers. [docs/SUBAGENTS.md](docs/SUBAGENTS.md)
4440

45-
```bash
46-
# Linux amd64
47-
curl -fsSL https://github.com/BackendStack21/kode/releases/latest/download/kode-linux-amd64 -o kode
48-
chmod +x kode && sudo mv kode /usr/local/bin/
41+
### 🧠 Skill System
42+
Trigger-matched `SKILL.md` files load on-demand. Auto-learn from patterns with `--learn`. Import skills from any URI with automatic LLM risk assessment before installation. [docs/CLI.md#skills](docs/CLI.md#skills)
4943

50-
# macOS arm64 (Apple Silicon)
51-
curl -fsSL https://github.com/BackendStack21/kode/releases/latest/download/kode-darwin-arm64 -o kode
52-
chmod +x kode && sudo mv kode /usr/local/bin/
53-
```
44+
### 💾 Persistent Memory
45+
Three tiers: **facts** (agent-managed durable entries), **session buffer** (auto-appended turn summaries), **episodes** (LLM-extracted knowledge from past sessions). Merge-on-write via go-vector RandomProjections — cosine >0.7 auto-merges, <0.3 auto-adds. Saves ~80% LLM calls. [docs/MEMORY.md](docs/MEMORY.md)
5446

55-
## Quick Start
47+
### 🔧 Multi-Turn Sessions
48+
Save, resume, list, trim, and clean up conversations. Sessions persist as JSON in `~/.kode/sessions/`. Continue any session with `kode continue`. [docs/SESSIONS.md](docs/SESSIONS.md)
5649

57-
```bash
58-
# Set your API key
59-
export DEEPSEEK_API_KEY=sk-...
50+
### 🏗️ Layerable Config
51+
Four-layer priority chain: `global (~/kode/config.json)` → `project (./kode.json)` → `KODE_*` env vars → CLI flags. `${VAR}` substitution in config files. [docs/CONFIG.md](docs/CONFIG.md)
6052

61-
# Run a task
62-
kode run "List the files in this directory"
53+
### 🔌 LLM-Agnostic
54+
Any OpenAI-compatible endpoint: Deepseek, OpenAI, Anthropic, Ollama, vLLM, Groq, Together, Fireworks — anything that speaks `/chat/completions`. Per-model profiles for thinking depth and context windows. [docs/PROVIDERS.md](docs/PROVIDERS.md)
6355

64-
# Save as session and continue
65-
kode run --session "Refactor the auth module"
66-
kode continue "Now add error handling"
56+
### 🌐 Web UI
57+
`kode serve` — browser-based agent with `@` resource completion (`@file.go`, `@sess:abc123`), WebSocket streaming, and a full IDE-style console. [docs/WEBUI.md](docs/WEBUI.md)
6758

68-
# Use a different model
69-
kode run --model gpt-4o --base-url https://api.openai.com/v1 "Explain this code"
59+
### 🔍 Native Tools
60+
Built-in `read_file`, `write_file`, `search_files`, `patch`, `shell`, and `browser` tools. All gated by a unified security layer (`dangerous` config) — classify operations as `allow` / `deny` / `prompt` per risk class. No third-party dependencies. [docs/SECURITY.md](docs/SECURITY.md)
7061

71-
# Sandboxed execution
72-
kode run --sandbox "npm test"
62+
---
7363

74-
# Enable skill learning (auto-detects patterns, suggests skills)
75-
kode run --learn "Set up a Go project with CI"
76-
```
77-
78-
## Documentation
79-
80-
| Topic | Doc |
81-
|-------|-----|
82-
| **CLI Reference** | [docs/CLI.md](docs/CLI.md) — commands, flags, examples |
83-
| **Configuration** | [docs/CONFIG.md](docs/CONFIG.md) — files, env vars, priority chain |
84-
| **Models & Profiles** | [docs/PROVIDERS.md](docs/PROVIDERS.md) — providers, thinking, context window |
85-
| **Multi-Turn Sessions** | [docs/SESSIONS.md](docs/SESSIONS.md) — save, continue, list, trim, cleanup |
86-
| **Sandboxing** | [docs/SANDBOXING.md](docs/SANDBOXING.md) — Docker isolation, security, config |
87-
| **Security** | [docs/SECURITY.md](docs/SECURITY.md) — prompt injection, sandbox model |
88-
| **Web UI** | [docs/WEBUI.md](docs/WEBUI.md) — `kode serve`, WebSocket protocol, `@` resource completion |
89-
| **Sub-Agents** | [docs/SUBAGENTS.md](docs/SUBAGENTS.md) — task decomposition, parallel OS-process sub-agents |
90-
| **Skills** | [docs/CLI.md#skills](docs/CLI.md#skills) — learn, list, save, import, curate |
91-
| **Development** | [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) — building, testing, contributing |
92-
93-
## Quick reference
64+
## Quick Start
9465

9566
```bash
96-
# Commands
97-
kode run [flags] <task> # Single-shot task
98-
kode run --learn [flags] <task> # Run with skill learning
99-
kode run --session [flags] <task> # Save as session
100-
kode continue [--id <id>] <task> # Continue a session
101-
kode session list # List sessions
102-
kode session show [id] # Show session transcript
103-
kode session delete <id> # Delete a session
104-
kode session trim <id> <n> # Keep last n messages
105-
kode session cleanup <days> # Delete old sessions
106-
kode skill list # List available skills
107-
kode skill view <name> # View a skill
108-
kode skill delete <name> # Delete a skill
109-
kode skill import <uri> [--basic --yes] # Import skill from URI
110-
kode skill curate # Quality/overlap audit
111-
kode serve [--addr :8080] [--open] # Web UI server
112-
kode subagent --goal <string> [flags] # Run a focused sub-task (JSON stdout)
113-
kode init [--global] [--force] # Create config file
114-
kode version # Print version
115-
116-
# Key flags
117-
--model <name> # LLM model (deepseek-v4-flash, gpt-4o...)
118-
--base-url <url> # API endpoint
119-
--sandbox # Docker sandbox mode
120-
--thinking <level> # enabled/disabled/low/medium/high
121-
--learn # Enable skill learning mode
122-
--system <prompt> # System prompt override
123-
--no-agents # Skip AGENTS.md
124-
```
125-
126-
## Features
67+
# Single-shot task
68+
kode run "List the files"
12769

128-
### Persistent Memory
70+
# With session persistence
71+
kode run --session "Refactor auth module"
72+
kode continue "Add rate limiting"
12973

130-
Three tiers managed automatically by the agent via the `memory` tool:
74+
# Sandboxed (Docker isolation)
75+
kode run --sandbox "npm audit"
13176

132-
| Tier | Storage | Cap | Managed by |
133-
|------|---------|-----|------------|
134-
| Facts | `~/.kode/memory/facts/{user,env}.md` | 1,500 + 2,500 chars | Agent via `memory` tool |
135-
| Buffer | In-session ring | 20 lines | Auto-appended each turn |
136-
| Episodes | `~/.kode/memory/episodes/<id>.md` | 1 KB each | LLM-extracted on session end |
77+
# Different model
78+
kode run --model gpt-4o --base-url https://api.openai.com/v1 "Explain this"
13779

138-
The agent can **add**, **replace**, **remove**, **consolidate**, **read**, or **search** memory using a single `memory` tool with six actions.
80+
# With skill learning
81+
kode run --learn "Set up a Go project with CI"
13982

140-
**Merge-on-write** uses go-vector RandomProjections to detect duplicate entries before writing — cosine >0.7 auto-merges, <0.3 auto-adds, 0.3-0.7 asks the LLM. Saves ~80% of LLM calls.
83+
# Interactive REPL
84+
kode repl
85+
```
14186

142-
See [docs/MEMORY.md](docs/MEMORY.md) for the full design.
87+
---
88+
89+
## Cheatsheet
90+
91+
### Commands
92+
93+
| Command | What it does |
94+
|---------|-------------|
95+
| `kode run <task>` | Single-shot task |
96+
| `kode run --session <task>` | Save conversation as session |
97+
| `kode continue [--id <id>] <task>` | Resume a saved session |
98+
| `kode repl` | Interactive multi-turn REPL |
99+
| `kode session list` | List recent sessions |
100+
| `kode session show [id]` | View session transcript |
101+
| `kode session delete <id>` | Delete a session |
102+
| `kode session trim <id> <n>` | Keep last n messages |
103+
| `kode session cleanup <days>` | Delete old sessions |
104+
| `kode skill list` | List available skills |
105+
| `kode skill view <name>` | View skill content |
106+
| `kode skill delete <name>` | Delete a skill |
107+
| `kode skill import <uri>` | Import skill from URL |
108+
| `kode skill curate` | Audit skill quality/overlap |
109+
| `kode serve [--addr :8080]` | Start Web UI server |
110+
| `kode subagent --goal <string>` | Run a focused sub-task |
111+
| `kode init [--global]` | Create config file |
112+
| `kode version` | Print version |
113+
114+
### Key Flags
115+
116+
| Flag | What it does |
117+
|------|-------------|
118+
| `--model <name>` | LLM model (e.g. deepseek-v4-flash, gpt-4o) |
119+
| `--base-url <url>` | API endpoint URL |
120+
| `--sandbox` | Run in Docker sandbox |
121+
| `--thinking <level>` | Reasoning depth (enabled/disabled/low/medium/high) |
122+
| `--learn` | Enable skill learning mode |
123+
| `--system <prompt>` | Override system prompt |
124+
| `--max-iter <n>` | Max think→act cycles (default 90) |
125+
| `--no-agents` | Skip AGENTS.md project file |
126+
127+
---
128+
129+
## Docs
130+
131+
| Doc | Covers |
132+
|-----|--------|
133+
| [CLI Reference](docs/CLI.md) | All commands, subcommands, flags, error codes |
134+
| [Configuration](docs/CONFIG.md) | Config files, env vars, priority chain, all sections |
135+
| [Providers & Models](docs/PROVIDERS.md) | Supported providers, thinking config, context windows |
136+
| [Memory](docs/MEMORY.md) | Three-tier design, go-vector merge-on-write, `memory` tool |
137+
| [Sessions](docs/SESSIONS.md) | Multi-turn conversations, save/resume/trim/cleanup |
138+
| [Sandboxing](docs/SANDBOXING.md) | Docker isolation model, config, security hardening |
139+
| [Security](docs/SECURITY.md) | Threat model, prompt injection defense, sandbox model |
140+
| [Sub-Agents](docs/SUBAGENTS.md) | Task decomposition, delegation tool, subagent protocol |
141+
| [Web UI](docs/WEBUI.md) | `kode serve`, WebSocket protocol, `@` resource resolution |
142+
| [Skills](docs/CLI.md#skills) | Trigger-matched skills, learning, import, curation |
143+
| [Development](docs/DEVELOPMENT.md) | Building, testing, contributing, project structure |
144+
145+
---
143146

144147
## Programmatic API
145148

146149
```go
150+
import "github.com/BackendStack21/kode"
151+
147152
agent, err := kode.New(kode.Config{
148-
Model: "deepseek-chat",
149-
APIKey: os.Getenv("DEEPSEEK_API_KEY"),
150-
Tools: []kode.Tool{&myTool{}},
153+
Model: "deepseek-chat",
154+
APIKey: os.Getenv("DEEPSEEK_API_KEY"),
155+
MaxIterations: 30,
156+
Tools: []kode.Tool{&myCustomTool{}},
157+
SystemMessage: "You are an expert at refactoring Go code.",
151158
})
152159
defer agent.Close()
153160

154-
result, err := agent.Run(context.Background(), "Summarize this codebase")
161+
result, err := agent.Run(context.Background(), "Refactor this module")
155162
```
156163

157-
## Test count
164+
The full `Config` struct supports: `BaseURL`, `Thinking`, `SandboxCleanup`, `Renderer`, `MemoryConfig`, `MemoryDir`, `Skills`, `SkillManager`, and `NoProjectFile`.
165+
166+
---
167+
168+
## Test
158169

159170
```bash
160-
go test ./...
161-
# 220+ tests, all pass, zero external dependencies
171+
go test ./... # 220+ tests, all pass
172+
go test -race ./... # race detector clean
173+
go test -cover ./... # 80%+ coverage
162174
```
163175

176+
Everything runs with `go test` — no Docker, no network, no external services required for unit tests.
177+
178+
---
179+
164180
## License
165181

166182
MIT

0 commit comments

Comments
 (0)