https://github.com/backendstack21/odek
Minimal Go autonomous agent runtime — 5 deps, ~11 MB, instant startup. One binary. One loop. Zero frameworks. ReAct (Reasoning + Acting) — think, therefore act.
https://github.com/backendstack21/odek
Last synced: 13 days ago
JSON representation
Minimal Go autonomous agent runtime — 5 deps, ~11 MB, instant startup. One binary. One loop. Zero frameworks. ReAct (Reasoning + Acting) — think, therefore act.
- Host: GitHub
- URL: https://github.com/backendstack21/odek
- Owner: BackendStack21
- License: mit
- Created: 2026-05-17T15:22:46.000Z (21 days ago)
- Default Branch: main
- Last Pushed: 2026-05-23T12:08:57.000Z (15 days ago)
- Last Synced: 2026-05-23T12:15:40.274Z (15 days ago)
- Language: Go
- Homepage: https://kode.21no.de/
- Size: 8.88 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: docs/SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# odek
**Minimal Go autonomous agent runtime — 5 deps, ~11 MB, instant startup.**
One binary. One loop. Zero frameworks. ReAct (Reasoning + Acting) — think, therefore act.
```bash
# Install
go install github.com/BackendStack21/odek/cmd/odek@latest
# Use (set ODEK_API_KEY, DEEPSEEK_API_KEY, or OPENAI_API_KEY)
export ODEK_API_KEY=sk-...
odek run "How many lines in go.mod?"
# → 3 lines
```
---
## Why odek
odek is not a framework. It's a **runtime** — the smallest possible surface area between an LLM and your tools.
| | odek | Python agents (LangChain, CrewAI, etc.) |
|---|---|---|
| Dependencies | **5.** 3× stdlib, 2× 21no.de | 200+ packages |
| Binary size | ~11 MB static | 50-200 MB with venv |
| Startup | **Instant** | 2-10s (Python imports) |
| Sandbox | `--sandbox` flag | Requires manual Docker setup |
| Tool interface | One interface, one method | Class hierarchies + decorators |
---
## Strategic Features
### 🔒 Sandboxed Execution
`odek run --sandbox` — every session spawns an isolated Docker container. No network, no host mounts beyond the working directory, zero capabilities, destroyed on exit. `--ctx` files are automatically injected into the container at `/workspace/`. Full security model in [docs/SANDBOXING.md](docs/SANDBOXING.md).
### 🧩 Sub-Agent Delegation
Parallel OS-process sub-agents via `delegate_tasks`. True isolation — each sub-agent is a fresh `odek subagent` process with its own config, tools, and termination timeout. Up to 8 concurrent workers. [docs/SUBAGENTS.md](docs/SUBAGENTS.md)
### 🧠 Skill System (on by default)
Skill-matched `SKILL.md` files load on-demand. Auto-learns from patterns every session — detects multi-step procedures, error recoveries, repeated actions, and user corrections. **LLM-enhanced**: each detected pattern is enriched with an LLM-generated name, description, trigger keywords, and structured body with overview, steps, pitfalls, and verification sections. Use `--no-learn` to disable. Import skills from any URI with automatic LLM risk assessment. [docs/CLI.md#skills](docs/CLI.md#skills)
### 💾 Persistent Memory
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)
### 🔧 Multi-Turn Sessions
Save, resume, list, trim, and clean up conversations. Sessions persist as JSON in `~/.odek/sessions/`. Continue any session with `odek continue`. [docs/SESSIONS.md](docs/SESSIONS.md)
### 🏗️ Layerable Config
Four-layer priority chain: `global (~/.odek/config.json)` → `project (./odek.json)` → `ODEK_*` env vars → CLI flags. `${VAR}` substitution in config files. [docs/CONFIG.md](docs/CONFIG.md)
### 🔌 LLM-Agnostic
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)
### 🌐 Web UI
`odek serve` — browser-based agent with `@` resource completion (`@file.go`, `@sess:abc123`), **drag-and-drop file attachments**, WebSocket streaming, and a full IDE-style console. [docs/WEBUI.md](docs/WEBUI.md)
### 🤖 Telegram Bot
Run agent tasks directly from Telegram via long-polling. Supports slash commands (`/plan`, `/sessions`, `/resume`, `/prune`, `/help`, etc.), voice message transcription, photo analysis, conversation persistence across restarts, saved plan files, and daily token budgeting. No external Telegram libraries — built on stdlib `net/http`. [docs/TELEGRAM.md](docs/TELEGRAM.md)
### 📎 File Attachments
Attach files to any prompt with `--ctx` / `-c` (CLI), `@filename` inline references (CLI + REPL + Web UI), or drag-and-drop (Web UI). File content is injected as context blocks before the task — no tool calls needed. Comma-separate multiple files: `--ctx main.go,lib.go`. [docs/CLI.md#file-attachments](docs/CLI.md#file-attachments)
### 🔗 MCP (Two-Way)
**Server** (`odek mcp`) — expose odek's native tools (shell, read/write/search files, patch, browser) to Claude Code, Cursor, and any MCP client. **Client** (`mcp_servers` config) — odek connects to external MCP servers (Playwright, Fetch, GitHub, SQLite, etc.) and makes their tools available to the agent as `__`. Both directions in one binary. [docs/MCP.md](docs/MCP.md)
### 🔍 Native Tools
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)
---
## Quick Start
```bash
# Single-shot task
odek run "List the files"
# With session persistence
odek run --session "Refactor auth module"
odek continue "Add rate limiting"
# Sandboxed (Docker isolation)
odek run --sandbox "npm audit"
# Different model
odek run --model gpt-4o --base-url https://api.openai.com/v1 "Explain this"
# With skill learning (on by default — use --no-learn to disable)
odek run "Set up a Go project with CI"
# Interactive REPL
odek repl
# Attach files for context
odek run --ctx data.csv "analyze this"
odek run --ctx main.go,lib.go "compare these files"
odek run "@README.md what does this project do?"
```
---
## Cheatsheet
### Commands
| Command | What it does |
|---------|-------------|
| `odek run ` | Single-shot task |
| `odek run --session ` | Save conversation as session |
| `odek continue [--id ] ` | Resume a saved session |
| `odek repl` | Interactive multi-turn REPL |
| `odek session list` | List recent sessions |
| `odek session show [id]` | View session transcript |
| `odek session delete ` | Delete a session |
| `odek session trim ` | Keep last n messages |
| `odek session cleanup ` | Delete old sessions |
| `odek skill list` | List available skills |
| `odek skill view ` | View skill content |
| `odek skill delete ` | Delete a skill |
| `odek skill import ` | Import skill from URL |
| `odek skill curate` | Audit skill quality/overlap |
| `odek serve [--addr :8080]` | Start Web UI server |
| `odek subagent --goal ` | Run a focused sub-task |
| `odek init [--global]` | Create config file |
| `odek mcp [--sandbox]` | Start MCP server — expose tools to Claude Code |
| `odek version` | Print version |
### Key Flags
| Flag | What it does |
|------|-------------|
| `--model ` | LLM model (e.g. deepseek-v4-flash, gpt-4o) |
| `--base-url ` | API endpoint URL |
| `--sandbox` | Run in Docker sandbox |
| `--thinking ` | Reasoning depth (enabled/disabled/low/medium/high) |
| `--learn` | Enable skill learning mode — on by default |
| `--no-learn` | Disable skill learning mode |
| `--system ` | Override system prompt |
| `--max-iter ` | Max think→act cycles (default 90) |
| `--prompt-caching` | Enable Anthropic/OpenAI/DeepSeek prompt caching markers |
| `--no-color` | Disable colored output |
| `--ctx ` / `-c` | Attach files as context blocks (comma-separated) |
| `--no-agents` | Skip AGENTS.md project file |
---
## Docs
| Doc | Covers |
|-----|--------|
| [CLI Reference](docs/CLI.md) | All commands, subcommands, flags, error codes |
| [Cheat Sheet](docs/CHEATSHEET.md) | CLI quick reference, key flags, config snippets |
| [Configuration](docs/CONFIG.md) | Config files, env vars, priority chain, all sections |
| [Programmatic API](docs/API.md) | **SDK Guide**: import, Agent lifecycle, Tool interface, multi-turn sessions, memory system, model profiles, complete examples |
| [Providers & Models](docs/PROVIDERS.md) | Supported providers, thinking config, context windows |
| [Prompt Caching](docs/CACHING.md) | Anthropic/OpenAI/DeepSeek caching support, config, metrics |
| [Memory](docs/MEMORY.md) | Three-tier design, go-vector merge-on-write, `memory` tool |
| [Sessions](docs/SESSIONS.md) | Multi-turn conversations, save/resume/trim/cleanup |
| [Telegram Bot](docs/TELEGRAM.md) | Telegram integration: bot client, slash commands, session management, plans, media downloads |
| [Sandboxing](docs/SANDBOXING.md) | Docker isolation model, config, security hardening |
| [Security](docs/SECURITY.md) | Threat model, prompt injection defense, sandbox model |
| [Sub-Agents](docs/SUBAGENTS.md) | Task decomposition, delegation tool, subagent protocol |
| [Web UI](docs/WEBUI.md) | `odek serve`, WebSocket protocol, `@` resource resolution |
| [Self-Learning](docs/LEARNING.md) | LLM-enhanced skill learning, pattern detection, auto-curation |
| [Skills](docs/CLI.md#skills) | Trigger-matched skills, learning, import, curation |
| [MCP](docs/MCP.md) | Serve tools to Claude Code + connect to external MCP servers |
| [Development](docs/DEVELOPMENT.md) | Building, testing, contributing, project structure |
---
## Programmatic API
```go
import "github.com/BackendStack21/odek"
agent, err := odek.New(odek.Config{
Model: "deepseek-v4-flash",
APIKey: os.Getenv("ODEK_API_KEY"),
MaxIterations: 30,
Tools: []odek.Tool{&myCustomTool{}},
SystemMessage: "You are an expert at refactoring Go code.",
})
defer agent.Close()
result, err := agent.Run(context.Background(), "Refactor this module")
```
The full `Config` struct supports: `BaseURL`, `Thinking`, `SandboxCleanup`, `Renderer`, `MemoryConfig`, `MemoryDir`, `Skills`, `SkillManager`, and `NoProjectFile`.
---
## Test
```bash
go test ./... # 1760+ tests, all pass (no setup required)
go test -race ./... # race detector clean
go test -cover ./... # overall coverage ~85%
```
Everything runs with `go test` — no Docker, no network, no external services required for unit tests.
Coverage highlights: `internal/tool` 100%, `internal/llm` 87.9%, `internal/loop` 89.4%, `internal/session` 89.7%, `internal/telegram` 86.9%, `internal/memory` 86.2%, `internal/skills` 86.3%.
---
## License
MIT