{"id":50189463,"url":"https://github.com/backendstack21/odek","last_synced_at":"2026-05-25T12:01:09.039Z","repository":{"id":358499674,"uuid":"1241589825","full_name":"BackendStack21/odek","owner":"BackendStack21","description":"Minimal Go autonomous agent runtime — 5 deps, ~11 MB, instant startup.  One binary. One loop. Zero frameworks. ReAct (Reasoning + Acting) — think, therefore act.","archived":false,"fork":false,"pushed_at":"2026-05-23T12:08:57.000Z","size":9311,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-23T12:15:40.274Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://kode.21no.de/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BackendStack21.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-17T15:22:46.000Z","updated_at":"2026-05-23T12:09:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/BackendStack21/odek","commit_stats":null,"previous_names":["backendstack21/kode","backendstack21/odek"],"tags_count":119,"template":false,"template_full_name":null,"purl":"pkg:github/BackendStack21/odek","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BackendStack21%2Fodek","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BackendStack21%2Fodek/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BackendStack21%2Fodek/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BackendStack21%2Fodek/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BackendStack21","download_url":"https://codeload.github.com/BackendStack21/odek/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BackendStack21%2Fodek/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33473706,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-25T06:32:55.349Z","status":"ssl_error","status_checked_at":"2026-05-25T06:32:35.322Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-25T12:01:08.060Z","updated_at":"2026-05-25T12:01:09.033Z","avatar_url":"https://github.com/BackendStack21.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# odek\n\n**Minimal Go autonomous agent runtime — 5 deps, ~11 MB, instant startup.**\n\nOne binary. One loop. Zero frameworks. ReAct (Reasoning + Acting) — think, therefore act.\n\n```bash\n# Install\ngo install github.com/BackendStack21/odek/cmd/odek@latest\n\n# Use (set ODEK_API_KEY, DEEPSEEK_API_KEY, or OPENAI_API_KEY)\nexport ODEK_API_KEY=sk-...\nodek run \"How many lines in go.mod?\"\n# → 3 lines\n```\n\n---\n\n## Why odek\n\nodek is not a framework. It's a **runtime** — the smallest possible surface area between an LLM and your tools.\n\n| | odek | Python agents (LangChain, CrewAI, etc.) |\n|---|---|---|\n| Dependencies | **5.** 3× stdlib, 2× 21no.de | 200+ packages |\n| Binary size | ~11 MB static | 50-200 MB with venv |\n| Startup | **Instant** | 2-10s (Python imports) |\n| Sandbox | `--sandbox` flag | Requires manual Docker setup |\n| Tool interface | One interface, one method | Class hierarchies + decorators |\n\n---\n\n## Strategic Features\n\n### 🔒 Sandboxed Execution\n`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).\n\n### 🧩 Sub-Agent Delegation\nParallel 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)\n\n### 🧠 Skill System (on by default)\nSkill-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)\n\n### 💾 Persistent Memory\nThree 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 \u003e0.7 auto-merges, \u003c0.3 auto-adds. Saves ~80% LLM calls. [docs/MEMORY.md](docs/MEMORY.md)\n\n### 🔧 Multi-Turn Sessions\nSave, 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)\n\n### 🏗️ Layerable Config\nFour-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)\n\n### 🔌 LLM-Agnostic\nAny 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)\n\n### 🌐 Web UI\n`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)\n\n### 🤖 Telegram Bot\nRun 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)\n\n### 📎 File Attachments\nAttach 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)\n\n### 🔗 MCP (Two-Way)\n**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 `\u003cserver\u003e__\u003ctool\u003e`. Both directions in one binary. [docs/MCP.md](docs/MCP.md)\n\n### 🔍 Native Tools\nBuilt-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)\n\n---\n\n## Quick Start\n\n```bash\n# Single-shot task\nodek run \"List the files\"\n\n# With session persistence\nodek run --session \"Refactor auth module\"\nodek continue \"Add rate limiting\"\n\n# Sandboxed (Docker isolation)\nodek run --sandbox \"npm audit\"\n\n# Different model\nodek run --model gpt-4o --base-url https://api.openai.com/v1 \"Explain this\"\n\n# With skill learning (on by default — use --no-learn to disable)\nodek run \"Set up a Go project with CI\"\n\n# Interactive REPL\nodek repl\n\n# Attach files for context\nodek run --ctx data.csv \"analyze this\"\nodek run --ctx main.go,lib.go \"compare these files\"\nodek run \"@README.md what does this project do?\"\n```\n\n---\n\n## Cheatsheet\n\n### Commands\n\n| Command | What it does |\n|---------|-------------|\n| `odek run \u003ctask\u003e` | Single-shot task |\n| `odek run --session \u003ctask\u003e` | Save conversation as session |\n| `odek continue [--id \u003cid\u003e] \u003ctask\u003e` | Resume a saved session |\n| `odek repl` | Interactive multi-turn REPL |\n| `odek session list` | List recent sessions |\n| `odek session show [id]` | View session transcript |\n| `odek session delete \u003cid\u003e` | Delete a session |\n| `odek session trim \u003cid\u003e \u003cn\u003e` | Keep last n messages |\n| `odek session cleanup \u003cdays\u003e` | Delete old sessions |\n| `odek skill list` | List available skills |\n| `odek skill view \u003cname\u003e` | View skill content |\n| `odek skill delete \u003cname\u003e` | Delete a skill |\n| `odek skill import \u003curi\u003e` | Import skill from URL |\n| `odek skill curate` | Audit skill quality/overlap |\n| `odek serve [--addr :8080]` | Start Web UI server |\n| `odek subagent --goal \u003cstring\u003e` | Run a focused sub-task |\n| `odek init [--global]` | Create config file |\n| `odek mcp [--sandbox]` | Start MCP server — expose tools to Claude Code |\n| `odek version` | Print version |\n\n### Key Flags\n\n| Flag | What it does |\n|------|-------------|\n| `--model \u003cname\u003e` | LLM model (e.g. deepseek-v4-flash, gpt-4o) |\n| `--base-url \u003curl\u003e` | API endpoint URL |\n| `--sandbox` | Run in Docker sandbox |\n| `--thinking \u003clevel\u003e` | Reasoning depth (enabled/disabled/low/medium/high) |\n| `--learn` | Enable skill learning mode — on by default |\n| `--no-learn` | Disable skill learning mode |\n| `--system \u003cprompt\u003e` | Override system prompt |\n| `--max-iter \u003cn\u003e` | Max think→act cycles (default 90) |\n| `--prompt-caching` | Enable Anthropic/OpenAI/DeepSeek prompt caching markers |\n| `--no-color` | Disable colored output |\n| `--ctx \u003cfiles\u003e` / `-c` | Attach files as context blocks (comma-separated) |\n| `--no-agents` | Skip AGENTS.md project file |\n\n---\n\n## Docs\n\n| Doc | Covers |\n|-----|--------|\n| [CLI Reference](docs/CLI.md) | All commands, subcommands, flags, error codes |\n| [Cheat Sheet](docs/CHEATSHEET.md) | CLI quick reference, key flags, config snippets |\n| [Configuration](docs/CONFIG.md) | Config files, env vars, priority chain, all sections |\n| [Programmatic API](docs/API.md) | **SDK Guide**: import, Agent lifecycle, Tool interface, multi-turn sessions, memory system, model profiles, complete examples |\n| [Providers \u0026 Models](docs/PROVIDERS.md) | Supported providers, thinking config, context windows |\n| [Prompt Caching](docs/CACHING.md) | Anthropic/OpenAI/DeepSeek caching support, config, metrics |\n| [Memory](docs/MEMORY.md) | Three-tier design, go-vector merge-on-write, `memory` tool |\n| [Sessions](docs/SESSIONS.md) | Multi-turn conversations, save/resume/trim/cleanup |\n| [Telegram Bot](docs/TELEGRAM.md) | Telegram integration: bot client, slash commands, session management, plans, media downloads |\n| [Sandboxing](docs/SANDBOXING.md) | Docker isolation model, config, security hardening |\n| [Security](docs/SECURITY.md) | Threat model, prompt injection defense, sandbox model |\n| [Sub-Agents](docs/SUBAGENTS.md) | Task decomposition, delegation tool, subagent protocol |\n| [Web UI](docs/WEBUI.md) | `odek serve`, WebSocket protocol, `@` resource resolution |\n| [Self-Learning](docs/LEARNING.md) | LLM-enhanced skill learning, pattern detection, auto-curation |\n| [Skills](docs/CLI.md#skills) | Trigger-matched skills, learning, import, curation |\n| [MCP](docs/MCP.md) | Serve tools to Claude Code + connect to external MCP servers |\n| [Development](docs/DEVELOPMENT.md) | Building, testing, contributing, project structure |\n\n---\n\n## Programmatic API\n\n```go\nimport \"github.com/BackendStack21/odek\"\n\nagent, err := odek.New(odek.Config{\n    Model:          \"deepseek-v4-flash\",\n    APIKey:         os.Getenv(\"ODEK_API_KEY\"),\n    MaxIterations:  30,\n    Tools:          []odek.Tool{\u0026myCustomTool{}},\n    SystemMessage:  \"You are an expert at refactoring Go code.\",\n})\ndefer agent.Close()\n\nresult, err := agent.Run(context.Background(), \"Refactor this module\")\n```\n\nThe full `Config` struct supports: `BaseURL`, `Thinking`, `SandboxCleanup`, `Renderer`, `MemoryConfig`, `MemoryDir`, `Skills`, `SkillManager`, and `NoProjectFile`.\n\n---\n\n## Test\n\n```bash\ngo test ./...                  # 1760+ tests, all pass (no setup required)\ngo test -race ./...           # race detector clean\ngo test -cover ./...          # overall coverage ~85%\n```\n\nEverything runs with `go test` — no Docker, no network, no external services required for unit tests.\n\nCoverage 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%.\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbackendstack21%2Fodek","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbackendstack21%2Fodek","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbackendstack21%2Fodek/lists"}