{"id":48796947,"url":"https://github.com/raoptimus/kodrun","last_synced_at":"2026-05-25T14:05:05.015Z","repository":{"id":350563580,"uuid":"1197227305","full_name":"raoptimus/kodrun","owner":"raoptimus","description":"Local CLI agent for Go development powered by Ollama. Auto-fixes build/test/lint errors, supports MCP tools, RAG search, and rich TUI.","archived":false,"fork":false,"pushed_at":"2026-04-10T22:48:20.000Z","size":290,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-11T00:23:30.641Z","etag":null,"topics":["ai-agents","cli","code-generation","developer-tools","go","llm","local-llm","ollama","qwen","qwen3","rag","vibe-coding"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/raoptimus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-03-31T12:26:10.000Z","updated_at":"2026-04-10T22:48:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/raoptimus/kodrun","commit_stats":null,"previous_names":["raoptimus/kodrun"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/raoptimus/kodrun","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raoptimus%2Fkodrun","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raoptimus%2Fkodrun/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raoptimus%2Fkodrun/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raoptimus%2Fkodrun/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/raoptimus","download_url":"https://codeload.github.com/raoptimus/kodrun/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raoptimus%2Fkodrun/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31776013,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T20:17:16.280Z","status":"ssl_error","status_checked_at":"2026-04-13T20:17:08.216Z","response_time":93,"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":["ai-agents","cli","code-generation","developer-tools","go","llm","local-llm","ollama","qwen","qwen3","rag","vibe-coding"],"created_at":"2026-04-14T00:00:48.754Z","updated_at":"2026-05-25T14:05:04.989Z","avatar_url":"https://github.com/raoptimus.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# KodRun\n\n[![Go Reference](https://pkg.go.dev/badge/github.com/raoptimus/kodrun.svg)](https://pkg.go.dev/github.com/raoptimus/kodrun/v2)\n[![Go Report Card](https://goreportcard.com/badge/github.com/raoptimus/kodrun)](https://goreportcard.com/report/github.com/raoptimus/kodrun)\n[![Test](https://github.com/raoptimus/kodrun/workflows/Test/badge.svg)](https://github.com/raoptimus/kodrun/actions)\n[![Coverage](https://github.com/raoptimus/kodrun/wiki/coverage.svg)](https://raw.githack.com/wiki/raoptimus/kodrun/coverage.html)\n[![GitHub Release](https://img.shields.io/github/release/raoptimus/kodrun.svg)](https://github.com/raoptimus/kodrun/releases)\n[![License](https://img.shields.io/github/license/raoptimus/kodrun)](https://github.com/raoptimus/kodrun/blob/main/LICENSE)\n\n\u003e **Beta** — this project is under active development. APIs and configuration may change.\n\nCLI agent for writing and maintaining code in **Go, Python and JavaScript/TypeScript**. Runs locally via [Ollama](https://ollama.com) or any **OpenAI-compatible API** (vLLM, llama.cpp, LiteLLM, etc.). Loads rules, snippets and documentation from the project working directory, executes tools (file operations, build/test/lint, git) and automatically fixes errors through the LLM.\n\nTested with **qwen3-coder:30b**, **qwen3.6**, **qwen3.5:35b-a3b**. For RAG (semantic code search) the **nomic-embed-text** embedding model is recommended.\n\n## Features\n\n- **Multi-provider LLM support** — Ollama (NDJSON streaming) and OpenAI-compatible APIs (SSE streaming) via a unified `Client` interface. Backends register via `init()` factory pattern.\n- **Multi-role orchestrator** — `planner` / `executor` / `reviewer` / `extractor` / `structurer` / `step_executor` / `response_classifier`, each role wired to its own provider profile.\n- **Parallel DAG plan execution** — approved plans run as a dependency graph of sub-agents with per-file locking.\n- **Multi-provider config** — one entry per (URL, model, temperature) profile; any role can point at any profile.\n- **Language-aware system prompts** — tool names, build/lint/test commands, and coding conventions in system prompts are adapted to the detected project language (Go, Python, JS/TS). When no language is detected, prompts contain no language-specific guidelines — the agent follows user instructions without bias toward any particular stack.\n- **Automatic project language \u0026 tech stack detection** — Go, Python, JS/TS; per-language tools auto-registered. Tech stack (gRPC, HTTP, Postgres, ClickHouse, MongoDB, Redis, Kafka) detected from dependencies for snippet filtering.\n- **Rules + snippets + custom commands** — `.kodrun/` driven, with `@`-reference validation at startup.\n- **RAG with multi-index** — semantic search over conventions + docs + snippets + embedded references. Architecture overview snippets are pinned verbatim in `/code-review`. Configurable backend: local (in-memory with disk persistence) or Muninn DB.\n- **`/code-review` command** — per-file code review pipeline. Pre-loads file contents, RAG snippets and dependency signatures, then reviews each file in parallel (no tool-calling required during review). Unchanged files are served from disk cache (`.kodrun/cache/review/`). Includes a separate architecture review pass. Results are merged, deduplicated and presented as a structured plan. Live LLM streaming in transcript view (`Ctrl+O`).\n- **Three operating modes** — **plan** (read-only analysis), **edit** (full tool access), **chat** (free-form discussion with read-only tools). Toggle with `Shift+Tab` (cycles plan → edit → chat → plan). Set default via `agent.default_mode`.\n- **Edit nudge** — auto-correction for models that respond with prose instead of tool calls in EDIT mode; prevents plan-shaped text from being silently accepted.\n- **`web_fetch` tool** — download web pages, convert HTML to markdown, and optionally index via RAG for semantic search.\n- **TUI** — fullscreen bubbletea interface, markdown rendering, confirm card with diff preview, step-level confirmation, RAG indexing progress, cache stats. Plain stdout mode for pipes/scripts.\n- **Tool-call result cache** — repeated read-only calls are served from cache.\n- **MCP (Model Context Protocol)** support for external tool servers.\n- **Security** — path traversal protection, `forbidden_patterns`, executor write-whitelist scoped to the approved plan.\n- **Context management** — auto-compaction on overflow with incremental summarization, smart truncation (preserves head+tail), tool-call boundary awareness, and token estimation auto-calibration from API responses.\n- **CI** — GitHub Actions pipeline with lint, test and coverage upload.\n\n## Quick Start\n\n### Requirements\n\n- Go 1.25+\n- [Ollama](https://ollama.com) with a loaded chat model and (optional) embedding model\n\n### Installation\n\n```bash\ngo install github.com/raoptimus/kodrun/cmd/kodrun@latest\n```\n\nOr from source:\n\n```bash\ngit clone https://github.com/raoptimus/kodrun.git\ncd kodrun\nmake install\n```\n\n### Launch\n\n```bash\n# Make sure Ollama is running\nollama serve\n\n# Pull the chat model\nollama pull qwen3-coder:30b\n\n# (Optional) Pull the embedding model for RAG\nollama pull nomic-embed-text\n\n# Interactive mode (TUI)\nkodrun\n\n# Initialize a new project (creates .kodrun/ starter layout)\ncd your-project\nkodrun init\n```\n\nLanguage (Go / Python / JS-TS) is detected automatically from project markers (`go.mod`, `pyproject.toml`, `package.json`, …). Override via `agent.project_language` if needed.\n\n## Usage\n\n### Interactive mode\n\n```bash\n# TUI with fullscreen interface\nkodrun\n\n# Plain stdout (no TUI) — useful in pipes and CI\nkodrun --no-tui\n```\n\n### Operating modes\n\nKodRun has three modes, toggled with `Shift+Tab` (cycles plan → edit → chat → plan):\n\n| Mode | Description | Available tools |\n|------|-------------|-----------------|\n| **plan** | Read-only analysis. Creates numbered plans without writing code. | read_file, grep, git_status, ... |\n| **edit** | Full tool access. Executes plans, writes/edits files, runs build/lint/test. | all tools |\n| **chat** | Free-form discussion. Answer questions, explain code, discuss architecture. | read_file, grep, git_status, ... |\n\nSet default mode in config: `agent.default_mode: \"plan\"` (default), `\"edit\"`, or `\"chat\"`.\n\n### One-shot task\n\n```bash\n# From the command line\nkodrun -- \"write a unit test for ParseConfig\"\n\n# Via make\nmake task TASK=\"add godoc to public functions in auth.go\"\n\n# Via pipe\necho \"write tests for auth.go\" | kodrun --no-tui\n```\n\n### Subcommands with auto-fix\n\n```bash\n# Build the project; on errors — LLM fixes and retries\nkodrun build\n\n# Run tests with auto-fix\nkodrun test ./internal/config/...\n\n# Linter with auto-fix\nkodrun lint\n\n# Fix a specific file\nkodrun fix internal/agent/agent.go\n```\n\n### Built-in slash commands\n\nAvailable inside the interactive TUI. Type `/` to see the full list.\n\n| Command | Description |\n|---------|-------------|\n| `/code-review` | Per-file code review with pre-loaded context (file contents, RAG snippets, dependency signatures), disk cache for unchanged files, and architecture review pass. |\n| `/orchestrate` | Run the full Plan → Execute → Review pipeline on a task. |\n| `/edit` | Switch to edit mode (full toolset). |\n| `/init` | Create the `.kodrun/` starter structure in the current project. |\n| `/diff` | Show the current uncommitted diff. |\n| `/compact` | Summarize the conversation to free up context. |\n| `/clear` | Clear conversation context. |\n| `/resume`, `/sessions` | Resume last saved session or list saved sessions. |\n| `/reindex`, `/rag`, `/add_doc` | Manage the RAG index. |\n| `/model` | Switch LLM model for the current session. |\n| `/exit` | Exit KodRun. |\n\nProject-specific commands defined in `.kodrun/commands/*.md` are listed alongside the built-ins.\n\n### Flags\n\n| Flag | Description | Default |\n|------|-------------|---------|\n| `--model` | Ollama model (overrides config) | from config |\n| `--work-dir` | Working directory | `.` |\n| `--no-tui` | Plain stdout mode | `false` |\n| `--no-fix` | Disable auto-fix | `false` |\n| `--config` | Config file path | auto-detect |\n| `--verbose` | Verbose output | `false` |\n\n### Environment variables\n\n| Variable | Description |\n|----------|-------------|\n| `KODRUN_MODEL` | Ollama model (overrides config) |\n| `KODRUN_OLLAMA_URL` | Ollama API URL (legacy; prefer `providers.*.base_url`) |\n| `KODRUN_WORK_DIR` | Working directory |\n| `KODRUN_NO_TUI` | `1` or `true` — disable TUI |\n\n## Configuration\n\nConfig is resolved in this order (each level overrides the previous):\n\n1. Built-in defaults\n2. `~/.config/kodrun/config.yaml` — global config\n3. `.kodrun/kodrun.yaml` in the project root — project config\n4. Environment variables\n5. Command-line flags\n\nSee [`examples/kodrun.yaml`](examples/kodrun.yaml) for a fully annotated project config and [`examples/global-config.yaml`](examples/global-config.yaml) for the global-config example.\n\n### ⚠️ Migrating from beta1\n\n- `rag.embedding_model` is **removed** — use `providers.embed.model` + `rag.provider: embed`.\n- The `ollama:` section is now a legacy fallback, only used when `providers:` is empty. Prefer `providers:`.\n- `temperature` now lives on the provider profile, not on `agent:`.\n- Rule `@`-references must point at `.kodrun/` (not `.claude/`). Broken references are logged via `slog.Warn` at startup.\n\n### ⚠️ Migrating from beta2\n\n- `agent.max_workers` is **renamed** to `agent.max_tool_workers`.\n- RAG **no longer indexes project source code**. Only `.kodrun/rules/`, `.kodrun/snippets/`, `.kodrun/docs/` and embedded language standards are indexed. Source files are read live via `read_file`.\n- `rag.index_dirs`, `rag.exclude_dirs` and `rag.max_chunks_per_file` are **deprecated** (kept for config compatibility, ignored at runtime).\n- New option `agent.specialist_timeout` (default `5m`) — wall-time cap for a single review phase.\n- New option `rag.review_budget_bytes` (default `24576`) — hard cap on RAG prefetch block in `/code-review` prompts.\n\n### ⚠️ Migrating from beta3\n\n- **V1 specialist fan-out pipeline removed.** `/code-review` now uses a V2 pipeline that pre-loads all context (file contents, RAG snippets, dependency signatures) per file and reviews in parallel without tool-calling. The `agent.orchestrator` toggle and `agent.specialist_timeout` option are no longer used.\n- **Review cache.** Per-file review results are cached on disk in `.kodrun/cache/review/`. Unchanged files are not re-reviewed on subsequent runs.\n- **Tech stack detection.** Project technologies (gRPC, HTTP, Postgres, ClickHouse, MongoDB, Redis, Kafka) are auto-detected from `go.mod` and `.proto` files. Snippets with a `requires` field are filtered by detected tech stack.\n- New option `agent.think` (default `false`) — enables thinking mode for planners and reviewers.\n\n### ⚠️ Migrating to v1.2.0-beta\n\n- **OpenAI-compatible backend.** New provider type `openai` for vLLM, llama.cpp, LiteLLM and other OpenAI-compatible servers. Set `type: openai` and `api_key` on the provider profile.\n- **Legacy `internal/ollama` package removed.** All consumers migrated to the unified `internal/llm` interface. If you have custom forks, update imports from `internal/ollama` to `internal/llm/ollama`.\n- **Language-aware prompts.** System prompts for planner, executor, and reviewer roles now use language-specific tool names (`go_build` / `tsc` / `ruff`, etc.) and conventions instead of hardcoded Go references. No config changes needed — this is automatic.\n- **Plan revision preserves context.** When you add a remark after planning, the revision agent now receives the original task context (including RAG and source code), not just the extracted plan text.\n- **RAG backend selection.** New option `rag.backend` (`local` or `muninn`). Default is `local` (unchanged). Muninn backend delegates embeddings to an external Muninn DB server.\n- **Live LLM streaming.** During `/code-review`, press `Ctrl+O` to open transcript view with real-time LLM output streaming.\n\n### ⚠️ Migrating to v1.3.0-beta\n\n- **Chat mode.** New operating mode for free-form discussion with read-only tool access. Toggle with `Shift+Tab` (cycles plan → edit → chat → plan). Set as default via `agent.default_mode: \"chat\"`.\n- **`/model` command.** Switch the active LLM model mid-session via an interactive picker. The toolbar updates immediately.\n- **Token auto-calibration.** Token estimates self-correct using actual prompt token counts from API responses (EMA-based). No config needed.\n- **Planner context enrichment.** Structurer now extracts per-step `context` and plan-level `context` fields. Step executors receive detailed task context, pre-read source files, and auto-enriched `rule_names`.\n- **Improved context compaction.** Smart truncation preserves both head and tail of long strings; incremental summarization merges previous summaries; tool-call/result pairs are never split across trim boundaries.\n- **Graceful tool errors.** `read_file`, `list_dir`, and `delete_file` return a result message instead of an error for non-existent paths.\n- **Autocomplete scrolling.** Slash-command list now scrolls when items exceed the visible area.\n\n### ⚠️ Migrating to v1.4.0-beta\n\n- **Verifier loop.** After the executor finishes all plan steps, a lightweight `verifier` sub-agent re-reads the changed files and confirms every step was actually completed. If gaps are found, it generates a targeted fix plan and re-runs the executor (up to `agent.max_replans` times). No config changes required — verifier uses `agent.thinking_provider`.\n- **Muninn API key.** New `rag.muninn.api_key` field for Bearer token authentication against a secured Muninn DB instance. Also new `rag.muninn.state_dir` — local directory for caching the chunk-set hash so unchanged content is not re-uploaded on restart.\n- **Internal refactor (no breaking changes).** `cmd/kodrun/main.go` is now a thin entry point; all CLI action handling moved to `internal/cliapp/`. `internal/agent/orchestrator.go` and `agent.go` split into focused modules (`orchestrator_plan.go`, `orchestrator_execute.go`, `orchestrator_findings.go`, `tool_executor.go`, etc.). The `llm.Client` interface is now composed of three narrow interfaces: `Chatter`, `Embedder`, `Inspector`.\n\n### Minimal `.kodrun/kodrun.yaml`\n\n```yaml\nproviders:\n  default:\n    base_url: \"http://localhost:11434\"\n    model: \"qwen3-coder:30b\"\n    context_size: 32768\n    temperature: 0.7\n  embed:\n    base_url: \"http://localhost:11434\"\n    model: \"nomic-embed-text\"\n\nagent:\n  provider: default\n  auto_fix: true\n\nrag:\n  enabled: true\n  provider: embed\n```\n\n### Providers \u0026 roles\n\nA **provider** is one combination of `base_url` / `model` / `timeout` / `context_size` / `temperature`. Roles inside the orchestrator are mapped to provider profiles through the `agent.*_provider` fields. Temperature lives on the profile — to get different temperatures for different roles, define multiple profiles.\n\n```yaml\nproviders:\n  default:\n    base_url: \"http://localhost:11434\"\n    model: \"qwen3-coder:30b\"\n    context_size: 32768\n    temperature: 0.7        # chat / executor\n  thinking:\n    base_url: \"http://localhost:11434\"\n    model: \"qwen3-coder:30b\"\n    context_size: 32768\n    temperature: 0.6        # planner + reviewer\n  precise:\n    base_url: \"http://localhost:11434\"\n    model: \"qwen3-coder:30b\"\n    context_size: 32768\n    temperature: 0.2        # deterministic edits\n  embed:\n    base_url: \"http://localhost:11434\"\n    model: \"nomic-embed-text\"\n\nagent:\n  provider: default           # chat + default fallback for unset roles\n  thinking_provider: thinking # planner + reviewer\n  executor_provider: precise  # executor + step_executor\n  extractor_provider: default # extractor + structurer (json/temp=0 forced automatically)\n```\n\nRole → provider mapping:\n\n| Role | Wired via | Purpose |\n|------|-----------|---------|\n| `planner` | `thinking_provider` | Writes the markdown plan |\n| `reviewer` | `thinking_provider` | Final pass over executor changes |\n| `executor`, `step_executor` | `executor_provider` | Applies the plan, whitelist-locked |\n| `extractor`, `structurer` | `extractor_provider` | Markdown → human / markdown → JSON `Plan{Steps[]}` (always json + temp=0) |\n| `response_classifier` | `provider` | Background TUI response classification |\n\n### Parallel plan execution\n\nTwo independent levels of parallelism:\n\n```yaml\nagent:\n  max_tool_workers: 4   # parallel read-only tool calls inside ONE sub-agent\n  max_parallel_tasks: 1   # parallel STEPS of an approved plan (DAG) — default sequential\n  max_replans: 2          # hard cap on REPLAN cycles within one run\n```\n\n- `max_tool_workers` caps how many read-only tool calls run concurrently inside a single chat turn.\n- `max_parallel_tasks` controls true plan parallelism: the approved plan is compiled into a DAG and independent steps are executed by separate sub-agents with per-file locking. Each parallel sub-agent gets a fresh history, its own read-path whitelist and its own per-step RAG bundle. Raise to 2–3 on a fast model/GPU to enable parallelism.\n\n## Rules\n\nKodRun loads `.md` files from `.kodrun/rules/` and includes them in the agent's system prompt. Rules are the primary way to customise agent behaviour for your project.\n\n### Rule file format\n\nStandard Markdown with optional front matter:\n\n```markdown\n---\npriority: high       # high | normal | low — inclusion order in the prompt\nscope: coding        # coding | review | fix | all\nglobs: \"internal/service/**\"   # optional — path-scoped rule\n---\n\n# Style rules\n\n- Use `errors.Is` instead of direct comparison\n- All public functions must have godoc\n```\n\nRules can reference shared documentation and examples via `@`-syntax:\n\n```markdown\nConventions: @.kodrun/docs/service.md\nExample:     @.kodrun/docs/example_service.go\nStyle guide: @.kodrun/docs/styleguide.md\n```\n\n`@`-references are resolved at load time and deduplicated. **Broken references are logged as warnings at startup** (`rule references missing file`) — typos no longer silently drop docs from the RAG index.\n\n### Example: `.kodrun/rules/style.md`\n\n```markdown\n---\npriority: high\nscope: coding\n---\n\n# Go style rules\n\n- Use `errors.Is`/`errors.As` instead of direct error comparison\n- All public functions must have godoc comments\n- Wrap errors with `fmt.Errorf(\"operation: %w\", err)`\n- Define sentinel errors as package-level `var`\n```\n\nSee more examples in [`examples/rules/`](examples/rules/).\n\n## Snippets\n\nSnippets are reusable code templates in `.kodrun/snippets/`. The agent retrieves them via the `snippets()` tool (by name, tag or file-path glob).\n\n### Snippet file format\n\nYAML front matter followed by the template body:\n\n```markdown\n---\ndescription: \"Standard HTTP handler\"\ntags: [http, handler]\nlang: go\nplaceholders:\n  EntityName: \"Name of the entity\"\n---\n\nfunc (h *Handler) Get{{EntityName}}(w http.ResponseWriter, r *http.Request) {\n    // handler implementation\n}\n```\n\n#### Front matter fields\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `description` | string | yes | Short description of the snippet |\n| `tags` | string[] | no | Tags for filtering and search |\n| `requires` | string[] | no | Technologies the project must use for this snippet to apply (see below) |\n| `paths` | string[] | no | Glob patterns for automatic matching by file path |\n| `lang` | string | no | Language identifier (`go`, `python`, `protobuf`, etc.) |\n| `placeholders` | map | no | Named placeholders to be replaced in the template |\n| `related` | string[] | no | Names of related snippets |\n\n#### Technology filtering with `requires`\n\nSnippets can declare which technologies the project must use for the snippet to be relevant. If the project does not use a required technology, the snippet is excluded from RAG indexing and the `snippets()` tool results.\n\nDetected technologies (for Go projects, based on `go.mod` dependencies and `.proto` files):\n\n`grpc`, `http`, `postgres`, `clickhouse`, `mongodb`, `redis`, `kafka`\n\nExample — a gRPC server snippet that is only relevant to projects using gRPC:\n\n```markdown\n---\ndescription: \"Template for gRPC server setup\"\ntags: [app, grpc, server]\nrequires: [grpc]\npaths: [\"**/app/**/application.go\"]\nlang: go\n---\n```\n\nSnippets without `requires` are always included regardless of the project's tech stack.\n\n### Pinned architecture overviews\n\nSnippets tagged with any of `architecture`, `overview` or `structure` are **pinned verbatim at the top of the `/code-review` RAG prefetch block**, regardless of semantic ranking. Use this for a project-wide map:\n\n```markdown\n---\ndescription: \"Project architecture overview — layers, dependency flow, archetypes\"\ntags: [architecture, structure, overview]\nlang: go\n---\n\n# Architecture\n\nGo microservice, clean architecture. Layers:\n\n- `cmd/\u003csvc\u003e/main.go` — bootstrap (CLI, Sentry, OTEL). No business logic.\n- `internal/app/\u003csvc\u003e/application.go` — composition root (DI wiring).\n- `internal/domain/` — business logic. Does not depend on transport or infrastructure.\n- `internal/dal/` — data access layer.\n- `internal/server/` — gRPC and HTTP transport.\n\nDependency direction: `transport → domain ← dal ← client`.\n```\n\nDuring `/code-review` the full text is injected into the architecture review prompt so the reviewer model sees the project map when analysing cross-cutting concerns.\n\n## Custom commands\n\nFiles in `.kodrun/commands/` define commands callable via `/command` in chat.\n\n### Example: `.kodrun/commands/review.md`\n\n```markdown\n---\ncommand: /review\ndescription: \"Run code review on a file\"\n---\n\nPerform a detailed code review of {{file}}.\nCheck for:\n- Bugs and logic errors\n- Error handling\n- Style violations\n- Missing tests\n- Performance issues\n```\n\nSee more examples in [`examples/commands/`](examples/commands/).\n\n## RAG (semantic search)\n\nKodRun indexes project files, rules, snippets and embedded reference docs, then performs semantic search to find relevant context. Especially useful for large codebases.\n\n```yaml\nproviders:\n  embed:\n    base_url: \"http://localhost:11434\"\n    model: \"nomic-embed-text\"      # the embedding model lives on the provider\n\nrag:\n  enabled: true\n  provider: embed                  # references the profile above\n  index_dirs: [\".\"]\n  chunk_size: 512\n  chunk_overlap: 32\n  top_k: 5\n```\n\nPull the embedding model first:\n\n```bash\nollama pull nomic-embed-text\n```\n\nThe RAG index is built in the background on startup. Progress is shown in the TUI status bar; the final count appears as `RAG indexed N new chunks (M total)`.\n\n## Available tools\n\nTools are **auto-registered based on the detected project language**. Read-only tools are also subject to the result cache.\n\n### File operations\n\n| Tool | Description |\n|------|-------------|\n| `read_file` | Read file contents |\n| `read_changed_files` | Diff with context for all git-changed source files (filtered by project language) |\n| `write_file` | Write a file (creates directories) |\n| `edit_file` | Find \u0026 replace text in a file |\n| `list_dir` | List files in a directory |\n| `find_files` | Find files by glob pattern |\n| `grep` | Search files by regex |\n| `delete_file` | Delete a file |\n| `create_dir` | Create a directory |\n| `move_file` | Move/rename a file |\n| `file_stat` | File metadata (size, permissions, modification time) without reading contents |\n| `bash` | Execute a shell command |\n| `web_fetch` | Fetch a web page, convert HTML to markdown (+ optional RAG indexing) |\n\n### Git\n\n| Tool | Description |\n|------|-------------|\n| `git_status` | Show git status and current branch |\n| `git_diff` | Show diff (optionally staged or against a ref) |\n| `git_log` | Show recent commits |\n| `git_commit` | Stage files and create a commit |\n\n### Go (auto-registered for Go projects)\n\n| Tool | Description |\n|------|-------------|\n| `go_build` | `go build` with error parsing |\n| `go_test` | `go test` with error parsing |\n| `go_lint` | `golangci-lint run` |\n| `go_fmt` | `gofmt -w` |\n| `go_vet` | `go vet` |\n| `go_mod_tidy` | `go mod tidy` |\n| `go_doc` | `go doc` lookup by package/symbol, or semantic search over indexed godoc via `query` |\n| `go_structure` | Show Go file/package structure (types, interfaces, functions, constants) with line numbers |\n\n### Python (auto-registered for Python projects)\n\n| Tool | Description |\n|------|-------------|\n| `python_run` | Run a Python script |\n| `pytest` | Run pytest |\n| `pip_install` | Install a package |\n| `ruff` | Ruff linter |\n| `black` | Black formatter |\n\n### JavaScript / TypeScript (auto-registered for JS/TS projects)\n\n| Tool | Description |\n|------|-------------|\n| `npm_install` | Install npm dependencies |\n| `npm_run` | Run an npm script |\n| `npm_test` | Run `npm test` |\n| `tsc` | TypeScript compiler |\n| `eslint` | ESLint |\n\n### Knowledge tools (always available)\n\n| Tool | Description |\n|------|-------------|\n| `search_docs` | Semantic search over the RAG index |\n| `get_rule` | Fetch a project rule by name |\n| `snippets` | Query `.kodrun/snippets/` by name, tag, path or query |\n\n## Security\n\n- All paths are resolved relative to the working directory; directory escape is blocked (path traversal protection).\n- `forbidden_patterns` in config block access to sensitive files.\n- The executor honours a write-whitelist scoped to the approved plan — sub-agents cannot touch files outside their step.\n- Rule `@`-references must resolve inside the project root; any attempt to escape is rejected.\n\n## Development\n\n```bash\nmake build          # Build the binary\nmake install        # Install to $GOPATH/bin\nmake test           # Unit tests\nmake lint           # Linter\nmake clean          # Clean artifacts\nmake help           # List all targets\n```\n\n## License\n\nBSD 3-Clause License\n[LICENSE](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraoptimus%2Fkodrun","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fraoptimus%2Fkodrun","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraoptimus%2Fkodrun/lists"}