{"id":50909937,"url":"https://github.com/icedmoca/kcode","last_synced_at":"2026-06-16T09:02:40.543Z","repository":{"id":355165397,"uuid":"1227027199","full_name":"icedmoca/kcode","owner":"icedmoca","description":"Kcode lets you run long, tool heavy coding sessions without blowing up token costs by compressing old context into references and only restoring exact data when needed, reducing hallucinations by grounding the model in real, retrievable source data instead of guesswork.","archived":false,"fork":false,"pushed_at":"2026-06-12T08:59:46.000Z","size":20274,"stargazers_count":19,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-12T09:13:18.816Z","etag":null,"topics":["claude-code","cli","codex","codex-cli","coding-cli","kcode","llm-inference","memory-retrieval","token-optimization"],"latest_commit_sha":null,"homepage":"","language":"Rust","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/icedmoca.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":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-02T05:35:32.000Z","updated_at":"2026-06-12T08:59:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/icedmoca/kcode","commit_stats":null,"previous_names":["icedmoca/kcode"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/icedmoca/kcode","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icedmoca%2Fkcode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icedmoca%2Fkcode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icedmoca%2Fkcode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icedmoca%2Fkcode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/icedmoca","download_url":"https://codeload.github.com/icedmoca/kcode/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icedmoca%2Fkcode/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34398408,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-16T02:00:06.860Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["claude-code","cli","codex","codex-cli","coding-cli","kcode","llm-inference","memory-retrieval","token-optimization"],"created_at":"2026-06-16T09:02:39.436Z","updated_at":"2026-06-16T09:02:40.523Z","avatar_url":"https://github.com/icedmoca.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"kcode.png\" alt=\"Kcode\" width=\"100%\" /\u003e\n\u003c/p\u003e\n\n# Kcode\n\nKcode is a Rust terminal agent for coding, debugging, provider experimentation, local model diagnostics, adaptive memory, and operational repair learning. It is designed to be hackable: the implementation is in this repository, the documentation is source-backed, and the validation scripts can detect stale inventory.\n\n## Quick install\n\nRun the installer, reload your shell path if needed, then start Kcode:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/icedmoca/kcode/main/install/install.sh | bash\nexec \"$SHELL\" -l\nkcode\n```\n\nIf you already cloned the repo locally, you can run:\n\n```bash\n./install.sh\nkcode\n```\n\n## Why Kcode exists\n\nKcode is built for developers who want a terminal-first coding agent that can:\n\n- inspect and edit the same workspace you are using;\n- call local tools and shell commands with visible results;\n- route across multiple model providers;\n- diagnose local LM Studio/OpenAI-compatible model servers;\n- remember useful operational signals locally;\n- learn recurring repair patterns from build, test, runtime, provider, auth, network, tooling, and context failures;\n- keep its documentation synchronized with what is actually implemented.\n\n## Current capabilities\n\n### Excellent adaptive memory\n\nKcode has a strong local memory system designed for real coding work. Its adaptive cognition layer records useful execution signals, retrieves compact prompt memory, and keeps prior operational context available without dumping entire transcripts back into every turn. On top of that, operational repair learning turns repeated build, test, provider, runtime, auth, network, tooling, and context failures into reusable repair motifs.\n\nThe result is memory that is practical rather than noisy: Kcode can carry forward what mattered, surface prior fixes when similar failures recur, and keep improving its repair instincts while staying deterministic, local, and testable. This makes Kcode especially good at long-running repository evolution where the agent benefits from remembering what worked, what failed, and what validation was needed.\n\n### Token savings from memory and local sidecar work\n\nKcode is designed to save tokens by remembering the right things instead of replaying everything. Adaptive cognition keeps compact, high-signal memory; repair learning stores concise failure→fix motifs; and the optional local sidecar model can handle cheaper support work such as summaries, routing hints, critique, memory compression, and local diagnostics. That means the expensive frontier model can spend more context on the current task while Kcode preserves continuity through compact local state.\n\nIn practice this helps long sessions stay efficient: less repeated explanation, less transcript bloat, fewer repeated investigations, and faster recovery when a familiar build or test failure returns. The local sidecar model is especially useful as a low-cost assistant for background understanding while the primary provider focuses on the hard reasoning step.\n\n### TUI and interaction\n\n- Chat-oriented terminal UI under `src/tui`.\n- Slash command registry with generated inventory in `docs/reference/implementation-inventory.md`.\n- Model picker, account picker, sidebars, status rendering, and rendering tests.\n- Context sidebar rows use a rainbow `∞` marker instead of a misleading dynamic context bar.\n- The local sidecar model can support UI-facing workflows by providing inexpensive summaries, command explanations, and compact context hints without spending premium provider tokens.\n\n### Agent runtime\n\n- Turn execution in `src/agent.rs` and runtime support crates.\n- Tool-call handling, streaming provider responses, turn admission, and result rendering.\n- Workspace-aware operation intended for iterative development and validation.\n- The local sidecar model can help with low-risk routing, summarization, and preflight analysis so the main agent turn keeps more context for decisions that need the strongest model.\n\n### Provider layer\n\n- Provider implementations under `src/provider`.\n- Routing, fallback, account failover, catalog refresh, streaming/SSE parsing, and provider-specific request shaping.\n- Local OpenAI-compatible diagnostics via `src/local_model.rs`.\n- The local sidecar model gives Kcode a cheap nearby model path for diagnostics, sanity checks, and fallback-style support when cloud calls are unnecessary or should be preserved.\n\n### Tools and integrations\n\n- Shell execution.\n- Patch/edit workflows.\n- Browser/search/MCP-style integrations where configured.\n- Benchmark and simulation binaries under `src/bin` and `crates`.\n- The local sidecar model can summarize tool output, compress noisy logs, and help decide which validation result matters before escalating back to the primary model.\n\n### Adaptive cognition and repair learning\n\n- `src/adaptive_cognition.rs` stores local execution signals and prompt-memory retrieval data.\n- `src/operational_repair_learning.rs` classifies failures, tracks recurrence, calibrates confidence, recommends replay gates, and emits compact repair memory.\n- Learned repair motifs are mirrored into adaptive cognition so future prompts can surface prior operational fixes.\n- The local sidecar model is a natural fit for memory compression: it can condense long histories, logs, and repeated failures into compact records that save tokens while preserving continuity.\n\n## Architecture at a glance\n\n```mermaid\nflowchart TD\n    User[Developer in terminal] --\u003e Entry{Entry point}\n\n    Entry --\u003e CLI[src/cli + src/main.rs]\n    Entry --\u003e TUI[src/tui app]\n    Entry --\u003e Bins[src/bin utilities]\n\n    CLI --\u003e Dispatch[CLI dispatch, auth, remote/headless, utility flows]\n    TUI --\u003e UIState[Chat state, input, slash commands, model/account pickers]\n    TUI --\u003e Info[Info widgets, sidebars, rainbow context ∞]\n    Bins --\u003e Bench[kcode-bench, tui-bench, harness/server utilities]\n\n    Dispatch --\u003e Runtime[src/agent.rs turn runtime]\n    UIState --\u003e Runtime\n    Bench --\u003e Runtime\n\n    Runtime --\u003e Prompt[Prompt/message assembly]\n    Runtime --\u003e Admission[Turn admission, cancellation, streaming coordination]\n    Runtime --\u003e Router[Provider/model routing]\n    Runtime --\u003e ToolLoop[Tool-call loop and result rendering]\n    Runtime --\u003e MemoryHooks[Memory + diagnostics hooks]\n\n    Router --\u003e Providers[src/provider adapters]\n    Providers --\u003e Failover[Fallback, account failover, catalog refresh]\n    Providers --\u003e Cloud[Hosted providers: Anthropic, OpenAI-compatible, Gemini, OpenRouter, Copilot, Cursor, Antigravity]\n    Providers --\u003e LocalCompat[Local/OpenAI-compatible endpoint]\n    LocalCompat --\u003e LMStudio[LM Studio / local GGUF server]\n\n    ToolLoop --\u003e Tools[src/tool]\n    Tools --\u003e Shell[Bash/process execution]\n    Tools --\u003e Edit[Patch/edit/file operations]\n    Tools --\u003e Search[agentgrep/code search]\n    Tools --\u003e Browser[Browser bridge]\n    Tools --\u003e MCP[MCP-style integrations]\n    Tools --\u003e Schedule[Scheduling/background checks]\n\n    MemoryHooks --\u003e Adaptive[src/adaptive_cognition.rs]\n    MemoryHooks --\u003e Repair[src/operational_repair_learning.rs]\n    MemoryHooks --\u003e LocalSidecar[Optional local sidecar model]\n\n    LocalSidecar --\u003e Compress[Summaries, critique, routing hints, log compression]\n    LocalSidecar --\u003e TokenSavings[Token savings and compact context]\n    Adaptive --\u003e PromptMemory[Compact prompt memory + execution signals]\n    Repair --\u003e Motifs[Failure classes, repair motifs, confidence, replay gates]\n    Motifs --\u003e Adaptive\n    PromptMemory --\u003e Prompt\n    TokenSavings --\u003e Prompt\n\n    Runtime --\u003e Validation[Focused validation: cargo check/test, smoke tests, benchmarks]\n    Validation --\u003e Repair\n    Validation --\u003e Docs[docs/reference inventory + scripts/validate_docs.py]\n    Docs --\u003e README[README and docs kept source-synchronized]\n```\n\n\nRead the full architecture guide: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).\n\n## Quick start\n\n```bash\ngit clone https://github.com/icedmoca/kcode.git\ncd kcode\ncargo build --release\n```\n\nFor operating-system-specific setup, PATH changes, WSL notes, Rust installation, native dependencies, and LM Studio setup, read [`docs/INSTALL.md`](docs/INSTALL.md).\n\n## Documentation map\n\n| Document | Purpose |\n| --- | --- |\n| [`docs/INSTALL.md`](docs/INSTALL.md) | Full install guide for Linux, macOS, Windows, and WSL, plus LM Studio setup. |\n| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Comprehensive subsystem architecture and implementation map. |\n| [`docs/OPERATIONS.md`](docs/OPERATIONS.md) | Development, validation, diagnostics, provider operations, local models, and repair learning. |\n| [`docs/reference/implementation-inventory.md`](docs/reference/implementation-inventory.md) | Generated inventory of binaries, slash commands, provider files, and public modules. |\n| [`docs/BENCHMARKS.md`](docs/BENCHMARKS.md) | Benchmark notes and historical benchmark context. |\n| [`docs/ABOUT.md`](docs/ABOUT.md) | Project background and extended notes. |\n\n## Common development loop\n\n```bash\ncargo fmt\ncargo check --lib\ncargo test --lib operational_repair_learning\npython3 scripts/validate_docs.py\n```\n\nUse focused tests for the subsystem you touched, then broaden validation before merging larger changes.\n\nYou can also run `/improve` inside the TUI to start safe recursive self-improvement. The command is intended to propose and execute bounded, reviewable improvements with validation instead of uncontrolled rewrites.\n\n## Supported model/provider matrix\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"Anthropic Claude Sonnet 4\" src=\"https://img.shields.io/badge/Anthropic-Claude%20Sonnet%204-6B46C1?style=for-the-badge\" /\u003e\n  \u003cimg alt=\"Anthropic Claude Opus\" src=\"https://img.shields.io/badge/Anthropic-Claude%20Opus-6B46C1?style=for-the-badge\" /\u003e\n  \u003cimg alt=\"OpenAI GPT-5\" src=\"https://img.shields.io/badge/OpenAI-GPT--5-00A67E?style=for-the-badge\" /\u003e\n  \u003cimg alt=\"OpenAI GPT-4.1\" src=\"https://img.shields.io/badge/OpenAI-GPT--4.1-00A67E?style=for-the-badge\" /\u003e\n  \u003cimg alt=\"OpenAI o-series\" src=\"https://img.shields.io/badge/OpenAI-o--series-00A67E?style=for-the-badge\" /\u003e\n  \u003cimg alt=\"Google Gemini 2.5 Pro\" src=\"https://img.shields.io/badge/Google-Gemini%202.5%20Pro-4285F4?style=for-the-badge\" /\u003e\n  \u003cimg alt=\"Google Gemini Flash\" src=\"https://img.shields.io/badge/Google-Gemini%20Flash-4285F4?style=for-the-badge\" /\u003e\n  \u003cimg alt=\"OpenRouter Kimi K2\" src=\"https://img.shields.io/badge/OpenRouter-Kimi%20K2-FF6B35?style=for-the-badge\" /\u003e\n  \u003cimg alt=\"OpenRouter DeepSeek\" src=\"https://img.shields.io/badge/OpenRouter-DeepSeek-FF6B35?style=for-the-badge\" /\u003e\n  \u003cimg alt=\"OpenRouter Qwen\" src=\"https://img.shields.io/badge/OpenRouter-Qwen-FF6B35?style=for-the-badge\" /\u003e\n  \u003cimg alt=\"OpenRouter Llama\" src=\"https://img.shields.io/badge/OpenRouter-Llama-FF6B35?style=for-the-badge\" /\u003e\n  \u003cimg alt=\"GitHub Copilot models\" src=\"https://img.shields.io/badge/GitHub%20Copilot-Copilot%20Models-181717?style=for-the-badge\" /\u003e\n  \u003cimg alt=\"Cursor models\" src=\"https://img.shields.io/badge/Cursor-Cursor%20Models-111111?style=for-the-badge\" /\u003e\n  \u003cimg alt=\"Antigravity models\" src=\"https://img.shields.io/badge/Antigravity-Provider%20Models-8A2BE2?style=for-the-badge\" /\u003e\n  \u003cimg alt=\"LM Studio local GGUF\" src=\"https://img.shields.io/badge/LM%20Studio-Local%20GGUF-2EA44F?style=for-the-badge\" /\u003e\n  \u003cimg alt=\"OpenAI-compatible local\" src=\"https://img.shields.io/badge/OpenAI--compatible-Local%20Server-2EA44F?style=for-the-badge\" /\u003e\n\u003c/p\u003e\n\nProvider/model availability depends on credentials, endpoint health, catalog refresh, and the specific adapter implementation under `src/provider`. The generated provider inventory is in [`docs/reference/implementation-inventory.md`](docs/reference/implementation-inventory.md).\n\n## Kcode UI cockpit\n\nKcode includes a local-first web cockpit under `ui/` for visualizing memory, context pressure, tool lanes, runtime events, git state, and the self-improvement loop.\n\nRun it locally:\n\n```bash\nscripts/kcodeui\n```\n\nThen open the URL printed by the server, usually:\n\n```text\nhttp://127.0.0.1:8768\n```\n\nThe server also exposes live state for the UI:\n\n```text\nhttp://127.0.0.1:8768/api/state\n```\n\nIntended slash command behavior after harness reload:\n\n```text\n/kcodeui\n```\n\nshould launch `scripts/kcodeui` or open `http://127.0.0.1:8768`. If the currently running harness build does not yet expose dynamic slash-command registration, run the script directly while the command registry catches up.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ficedmoca%2Fkcode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ficedmoca%2Fkcode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ficedmoca%2Fkcode/lists"}