# do_it
[](https://crates.io/crates/do_it)
[](LICENSE)
An autonomous coding agent that runs local LLMs via [Ollama](https://ollama.com) to read, write, and fix code in your repositories. Works on Windows and Linux with no shell dependency, no Python, no cloud APIs.
Inspired by [mini-swe-agent](https://mini-swe-agent.com/latest/) — a minimal, transparent approach to software engineering agents.
**do_it** extends that foundation with persistent memory, multi-role orchestration, sub-agents, GitHub integration, and a significantly expanded tool set.
Most of the new features were designed and implemented by [Claude Sonnet 4.6](https://www.anthropic.com/claude).
---
## Features
- **Local-first** — runs entirely on your machine via Ollama, no cloud APIs required
- **Cross-platform** — Windows (MSVC) and Linux, no shell operators, no Python
- **Agent roles** — focused tool sets and prompts per task type: `developer`, `navigator`, `qa`, `boss`, `research`, `reviewer`, `memory`
- **Sub-agent orchestration** — `boss` role delegates to specialised sub-agents via `spawn_agent`; results flow through shared memory
- **Persistent memory** — `.ai/` hierarchy: session notes, task plan, knowledge base, architectural decisions, lessons learned. Global `~/.do_it/` memory for user preferences and cross-project boss insights
- **Browser integration** — headless browser tools (`screenshot`, `browser_get_text`, `browser_action`, `browser_navigate`) via CDP; connect Chrome or Lightpanda by setting `cdp_url` in config
- **Agent self-improvement** — `tool_request` and `capability_gap` tools let the Boss record missing capabilities to `~/.do_it/tool_wishlist.md`; review to prioritise new tool development
- **Project auto-detection** — `.ai/project.toml` scaffolded on first run with commands, GitHub repo, and agent conventions
- **GitHub integration** — `github_api` tool for issues, PRs, branches, commits, file contents (token from env)
- **Test coverage** — `test_coverage` auto-detects Rust/Node/Python and runs the right tool
- **Telegram notifications** — `ask_human` for blocking questions, `notify` for non-blocking progress updates
- **Loop detection** — automatically detects stuck patterns and sends a Telegram alert
- **Model routing** — use different models per role (e.g. a large coder model for `developer`, a small fast one for `navigator`)
- **Vision support** — pass an image as `--task` for visual debugging (requires vision-capable model)
---
## Quick Start
```bash
# 1. Pull a model
ollama pull qwen3.5:9b
# 2. Install
cargo install do_it
# 3. Run
do_it run --task "Find and fix the bug in src/parser.rs" --repo /path/to/project
# With a role (recommended)
do_it run --task "Add input validation to handlers.rs" --role developer
# Orchestrate a complex task with sub-agents
do_it run --task "Add OAuth2 login to the API" --role boss --max-steps 80
```
---
## Roles
Each role restricts the agent to a focused set of tools and a role-specific system prompt. This is critical for smaller models — 6–8 tools instead of 20+ significantly improves output quality.
| `developer` | Write and edit code | read/write file, str_replace, run_command, git, AST, github_api, test_coverage, browser |
| `navigator` | Explore codebase structure | tree, find_files, search, outline, find_references |
| `research` | Find information | web_search, fetch_url, memory |
| `qa` | Run tests, verify changes | test_coverage, diff_repo, git_log, search, github_api, screenshot |
| `reviewer` | Static code review — no execution | read_file, search, outline, diff_repo, memory, screenshot |
| `boss` | Plan and orchestrate | memory, spawn_agent, web_search, ask_human, browser, tool_request |
| `memory` | Manage `.ai/` state | memory_read, memory_write |
```bash
do_it roles # list all roles and their tool allowlists
```
---
## Tools
**Filesystem:** `read_file`, `write_file`, `str_replace`, `list_dir`, `find_files`, `search_in_files`, `tree`
**Execution:** `run_command`, `diff_repo`, `test_coverage`
**Git:** `git_status`, `git_commit`, `git_log`, `git_stash`
**Internet:** `web_search` (DuckDuckGo, no API key), `fetch_url`, `github_api`
**Code intelligence** (Rust, TypeScript, JavaScript, Python, C++, Kotlin):
`get_symbols`, `outline`, `get_signature`, `find_references`
**Memory** (`.ai/` hierarchy): `memory_read`, `memory_write`
**Communication:** `ask_human` (Telegram or console), `notify` (one-way Telegram), `finish`
**Multi-agent:** `spawn_agent`
**Browser** (requires `[browser]` in config.toml): `screenshot`, `browser_get_text`, `browser_action`, `browser_navigate`
**Self-improvement:** `tool_request`, `capability_gap`
---
## Sub-agent Orchestration
The `boss` role can spawn specialised sub-agents. Sub-agents run in-process with isolated history and communicate through shared `.ai/knowledge/` memory.
```bash
do_it run --task "Add OAuth2 login" --role boss --max-steps 80
```
```
boss: reads last_session, plan, decisions, user_profile
│
├─ spawn_agent("research", "find best OAuth crates for Axum", memory_key="knowledge/oauth")
├─ spawn_agent("navigator", "locate existing auth middleware", memory_key="knowledge/structure")
├─ spawn_agent("developer", "implement OAuth per the plan")
├─ screenshot("http://localhost:3080/login") ← boss sees the result directly
├─ spawn_agent("reviewer", "review the OAuth implementation", memory_key="knowledge/review_report")
├─ spawn_agent("qa", "verify all tests pass", memory_key="knowledge/qa_report")
└─ notify("OAuth complete, all tests pass") → finish
```
---
## Persistent Memory
```
.ai/
├── project.toml ← auto-scaffolded on first run, edit freely
├── prompts/ ← custom role prompt overrides
├── state/
│ ├── current_plan.md ← boss writes task breakdown here
│ ├── last_session.md ← agent reads this on startup
│ ├── session_counter.txt
│ └── external_messages.md ← external inbox, read and cleared on startup
├── logs/history.md
└── knowledge/
├── lessons_learned.md ← QA appends project-specific patterns
├── decisions.md ← architectural decisions and rationale
└── qa_report.md ← latest test results
```
Global memory in `~/.do_it/` persists across all projects and is read by the `boss` role at startup:
| `user_profile.md` | Your preferences: language, stack, workflow style. Boss reads this every session. |
| `boss_notes.md` | Cross-project insights accumulated by Boss — patterns that apply beyond the current repo. |
| `tool_wishlist.md` | Missing capabilities recorded by the agent via `tool_request` and `capability_gap`. Review to prioritise new tool development. |
Edit `~/.do_it/user_profile.md` once and the boss will always know your stack and conventions.
---
## Configuration
```toml
# config.toml
ollama_base_url = "http://localhost:11434"
model = "qwen3.5:9b"
temperature = 0.0
max_tokens = 4096
history_window = 8
max_output_chars = 6000
# Optional: different models per role
[models]
coding = "qwen3-coder-next"
search = "qwen3.5:4b"
execution = "qwen3.5:4b"
# Optional: Telegram for ask_human and notify
# telegram_token = "..."
# telegram_chat_id = "..."
```
Config priority: `--config` flag → `./config.toml` → `~/.do_it/config.toml` → built-in defaults.
On first run, `~/.do_it/` is created with a full template including `user_profile.md`, `boss_notes.md`, and `tool_wishlist.md`.
```bash
do_it config # show resolved config
```
### Browser backend (optional)
```toml
[browser]
# Connect to a running CDP server — Chrome, Lightpanda, or any CDP-compatible browser
cdp_url = "ws://127.0.0.1:9222"
# Or launch Chrome locally (coming soon — requires chromiumoxide feature)
# chrome_path = "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"
# Screenshot output directory (default: .ai/screenshots)
# screenshot_dir = ".ai/screenshots"
```
Start a CDP server:
```bash
# Chrome
google-chrome --headless --remote-debugging-port=9222
# Lightpanda (lightweight, AI-optimised, 9x less RAM than Chrome)
lightpanda serve --host 127.0.0.1 --port 9222
# or via Docker:
docker run -d -p 9222:9222 lightpanda/browser:nightly
```
---
## CLI
```
do_it run --task <text|file|image>
--repo <path> (default: .)
--role <role> (default: unrestricted)
--config <path> (default: config.toml)
--system-prompt <text|file>
--max-steps <n> (default: 30)
do_it config [--config <path>]
do_it roles
```
---
## Roadmap
- [ ] `git_push` / `git_pull` structured tools
- [ ] `run_background(program, args, id)` — dev servers, keep-alive processes
- [ ] Browser CDP implementation (chromiumoxide backend behind `--features browser`)
- [ ] Parallel sub-agent execution via `tokio::join!`
- [ ] `do_it status` / `do_it init` CLI commands
- [ ] Tree-sitter backend for more accurate AST analysis
- [ ] Web search providers beyond DuckDuckGo
---
## Authors
Project concept inspired by [mini-swe-agent](https://mini-swe-agent.com/latest/).
Built by [Claude Sonnet 4.6](https://www.anthropic.com/claude) with <oleksandr.public@gmail.com>.
## License
MIT