{"id":47875970,"url":"https://github.com/eren23/attocode","last_synced_at":"2026-04-04T01:14:21.177Z","repository":{"id":334274468,"uuid":"1139370248","full_name":"eren23/attocode","owner":"eren23","description":"A series of lessons, 0 to hero ai coding agent building guide.","archived":false,"fork":false,"pushed_at":"2026-04-01T18:01:24.000Z","size":11364,"stargazers_count":14,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-02T10:32:32.880Z","etag":null,"topics":["agent","agentic-ai","ai","ai-coding","coding-agent","coding-assistant","deep-learning","education","from-scratch","learning-agents","llm","mcp","python","tutorial"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/eren23.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/roadmap.md","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-01-21T21:49:37.000Z","updated_at":"2026-04-01T18:00:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/eren23/attocode","commit_stats":null,"previous_names":["eren23/attocode"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/eren23/attocode","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eren23%2Fattocode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eren23%2Fattocode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eren23%2Fattocode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eren23%2Fattocode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eren23","download_url":"https://codeload.github.com/eren23/attocode/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eren23%2Fattocode/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31383919,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T23:20:52.058Z","status":"ssl_error","status_checked_at":"2026-04-03T23:20:51.675Z","response_time":107,"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":["agent","agentic-ai","ai","ai-coding","coding-agent","coding-assistant","deep-learning","education","from-scratch","learning-agents","llm","mcp","python","tutorial"],"created_at":"2026-04-04T01:14:20.567Z","updated_at":"2026-04-04T01:14:21.169Z","avatar_url":"https://github.com/eren23.png","language":"TypeScript","readme":"# Attocode\n\nProduction AI coding agent built in Python. Features a Textual-based TUI, multi-agent swarm orchestration, intelligent budget management, and a safety sandbox system.\n\n**[Documentation](https://eren23.github.io/attocode/)** | **[PyPI](https://pypi.org/project/attocode/)**\n\n## Features\n\n- **Interactive TUI** --- Rich terminal interface with live tool status, streaming, plan/task panels, and keyboard shortcuts (powered by [Textual](https://textual.textualize.io/))\n- **Single-turn mode** --- Run one-shot prompts from the command line for scripting and automation\n- **Swarm mode** --- Multi-agent orchestration with a standalone Python hybrid coordinator (`attoswarm`) and heterogeneous backends\n- **Budget management** --- Token-based economics with doom-loop detection, phase tracking, and budget extension dialogs\n- **Safety sandbox** --- Platform-aware command isolation (Seatbelt on macOS, Landlock on Linux, Docker, or allowlist fallback)\n- **Session persistence** --- SQLite-backed sessions, checkpoints, goals, audit logs, and permission grants that persist across prompts\n- **MCP support** --- Connect external tools via the Model Context Protocol\n- **Multi-provider** --- Anthropic, OpenRouter, OpenAI, Azure, and ZAI adapters\n- **Research campaigns** --- Multi-experiment research workflows with dedicated worktrees, hypothesis tracking, and persistent campaign state\n- **Skills \u0026 agents** --- Extensible skill and agent system with project-level and user-level customization\n\n## Requirements\n\n- Python 3.12+\n- An API key for at least one LLM provider (e.g. `ANTHROPIC_API_KEY`)\n\n## Installation\n\n### Development install (recommended)\n\n```bash\ngit clone https://github.com/eren23/attocode.git\ncd attocode\n\nuv sync --all-extras          # creates .venv, installs everything\n```\n\n### Global install (recommended for end users)\n\n```bash\ncd attocode\nuv tool install --force . --with anthropic --with openai\n```\n\nThis installs three commands globally: `attocode`, `attocodepy`, and `attoswarm`.\n\n### Optional provider extras\n\n```bash\nuv sync --extra anthropic     # Anthropic SDK (recommended)\nuv sync --extra openai        # OpenAI SDK\nuv sync --extra tree-sitter   # AST parsing for code analysis\nuv sync --extra semantic      # Semantic search embeddings (sentence-transformers)\nuv sync --extra dev           # Development tools (pytest, mypy, ruff)\nuv sync --all-extras          # All of the above\n```\n\nSet your API key:\n\n```bash\nexport ANTHROPIC_API_KEY=\"sk-ant-...\"\n# Or for OpenRouter:\nexport OPENROUTER_API_KEY=\"sk-or-...\"\n```\n\n## Quick Start\n\n**Single-turn** --- ask a question and get one response:\n\n```bash\nattocode \"List all Python files in this project\"\n```\n\n**Interactive TUI** --- launch the full terminal interface:\n\n```bash\nattocode\n```\n\n**Swarm mode** --- decompose a task across multiple parallel agents:\n\n```bash\nattocode --swarm \"Build a REST API for a todo app with tests\"\n```\n\n**Hybrid swarm mode** --- process-boundary orchestration via `attoswarm`:\n\n```bash\nattocode swarm start .attocode/swarm.hybrid.yaml \"Build a REST API for a todo app with tests\"\n```\n\n**Research campaign** --- run structured multi-experiment research:\n\n```bash\nattocode research start \"Evaluate caching strategies for the query layer\"\n```\n\n## Swarm Command Chooser\n\nUse these commands based on the scenario:\n\n```bash\n# New standalone swarm\nattocode swarm start .attocode/swarm.hybrid.yaml \"$(cat tasks/goal.md)\"\n\n# Follow-up / phase-2 swarm based on a previous swarm result\nattocode swarm continue .agent/hybrid-swarm/demo-1 --config .attocode/swarm.hybrid.yaml \"$(cat tasks/goal-phase2.md)\"\n\n# Resume the exact same run\nattoswarm resume .agent/hybrid-swarm/demo-1\n\n# Reattach the dashboard\nattocode swarm monitor .agent/hybrid-swarm/demo-1\n```\n\nImportant distinction:\n\n- `start` = new standalone run\n- `continue` = new child run from previous swarm output\n- `resume` = same run dir, same persisted goal\n\nUse `--tasks-file` only with structured decomposition files such as\n`tasks.yaml` or `tasks.md`, not with high-level goal docs like `goal.md`.\n\n## CLI Reference\n\n| Flag | Short | Description |\n|------|-------|-------------|\n| `PROMPT` | | Positional --- run single-turn with this prompt |\n| `--model` | `-m` | LLM model to use |\n| `--provider` | | LLM provider (`anthropic`, `openrouter`, `openai`, `azure`, `zai`) |\n| `--permission` | `-p` | Permission mode: `strict`, `interactive`, `auto-safe`, `yolo` |\n| `--yolo` | | Shorthand for `--permission yolo` (auto-approve all) |\n| `--task` | `-t` | Task description (alternative to positional prompt) |\n| `--max-tokens` | | Maximum response tokens |\n| `--temperature` | | LLM temperature (0.0--1.0) |\n| `--max-iterations` | `-i` | Maximum agent iterations |\n| `--timeout` | | Request timeout in seconds |\n| `--resume` | | Resume a previous session by ID |\n| `--tui` / `--no-tui` | | Force TUI or plain REPL mode |\n| `--theme` | | TUI theme (`dark`, `light`, `auto`) |\n| `--trace` | | Save JSONL execution traces to `.attocode/traces/` |\n| `--swarm` | | Enable swarm mode (optional: path to config YAML) |\n| `--swarm-resume` | | Resume a previous swarm session by ID |\n| `--hybrid` | | Route swarm execution to standalone `attoswarm` orchestrator |\n| `--paid-only` | | Only use paid models (no free tier) |\n| `--record` | | Record session for visual replay |\n| `--debug` | | Enable debug logging |\n| `--non-interactive` | | Run in non-interactive mode |\n| `--version` | | Show version and exit |\n\n## Architecture\n\n```\nsrc/attocode/\n  types/           Type definitions (messages, agent, config)\n  agent/           Core agent orchestrator and builders\n  core/            Execution loop, subagent spawner, tool executor\n  providers/       LLM provider adapters (Anthropic, OpenRouter, OpenAI, Azure, ZAI)\n  tools/           Built-in tool implementations (file ops, bash, search)\n  integrations/    Feature modules organized by domain:\n    budget/          Economics, budget pools, doom-loop detection\n    context/         Context engineering, compaction, codebase analysis\n    safety/          Policy engine, sandbox (seatbelt/landlock/docker)\n    persistence/     SQLite session store, checkpoints, goals\n    agents/          Shared blackboard, delegation protocol\n    tasks/           Task decomposition, planning, verification\n    skills/          Skill loading and execution\n    mcp/             MCP client and tool integration\n    quality/         Learning store, self-improvement, health checks\n    utilities/       Hooks, rules, routing, logging, retry\n    swarm/           Multi-agent orchestrator (20 modules, 10k+ lines)\n    streaming/       Streaming and PTY shell\n    lsp/             Language server protocol integration\n  tricks/          Context engineering techniques\n  tracing/         Trace collector, event types, cache boundary tracking\n  tui/             Textual TUI (app, widgets, dialogs, bridges, styles)\n```\n\n## Lessons\n\nThe [`lessons/`](lessons/) directory contains a **26-lesson course** teaching you to build production-ready AI coding agents from scratch. The lessons use TypeScript and cover everything from the core agent loop to multi-agent coordination.\n\n```bash\ncd lessons\nnpm install\nnpm run lesson:1\n```\n\nThe lessons are also available on the [documentation site](https://eren23.github.io/attocode/lessons/).\n\n## Legacy TypeScript Version\n\nThe [`legacy/`](legacy/) directory contains the original TypeScript implementation of Attocode (v0.2.6). The Python version is the active implementation and has surpassed the TypeScript version in features. See [`legacy/PORTING_REPORT.md`](legacy/PORTING_REPORT.md) for a detailed feature comparison.\n\n## Testing\n\n```bash\nuv run pytest tests/unit/ -x -q          # Quick unit tests\nuv run pytest tests/ --cov=src/attocode  # With coverage\nuv run ruff check src/ tests/            # Linting\n```\n\n## Documentation\n\nFull documentation is available at **[eren23.github.io/attocode](https://eren23.github.io/attocode/)**.\n\n- [Architecture](docs/ARCHITECTURE.md) --- Module relationships and data flow\n- [Providers](docs/PROVIDERS.md) --- LLM provider adapter reference\n- [Sandbox](docs/SANDBOX.md) --- Platform-aware command isolation\n- [Budget](docs/BUDGET.md) --- Token economics and doom-loop detection\n- [MCP](docs/MCP.md) --- Model Context Protocol integration\n- [Swarm Guide](docs/swarm-guide.md) --- Multi-agent orchestration\n- [Hybrid Swarm](docs/hybrid-swarm-operations.md) --- Start vs continue vs resume, monitor/detach flows, and runbook\n- [Research Campaigns](docs/research-guide.md) --- Multi-experiment research workflows with dedicated worktrees\n- [Contributing](CONTRIBUTING.md) --- How to contribute\n\n## License\n\nSee [LICENSE](LICENSE) for details.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feren23%2Fattocode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feren23%2Fattocode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feren23%2Fattocode/lists"}