{"id":35556646,"url":"https://github.com/elct9620/autonoe","last_synced_at":"2026-01-21T14:01:21.283Z","repository":{"id":331359340,"uuid":"1125853861","full_name":"elct9620/autonoe","owner":"elct9620","description":"The autonomous coding tool based on Claude Agent SDK","archived":false,"fork":false,"pushed_at":"2026-01-16T18:31:01.000Z","size":918,"stargazers_count":3,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-17T03:51:06.510Z","etag":null,"topics":["agent","autonomous-agents","claude-code"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/elct9620.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":null,"dco":null,"cla":null}},"created_at":"2025-12-31T13:55:12.000Z","updated_at":"2026-01-16T18:30:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/elct9620/autonoe","commit_stats":null,"previous_names":["elct9620/autonoe"],"tags_count":29,"template":false,"template_full_name":null,"purl":"pkg:github/elct9620/autonoe","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elct9620%2Fautonoe","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elct9620%2Fautonoe/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elct9620%2Fautonoe/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elct9620%2Fautonoe/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elct9620","download_url":"https://codeload.github.com/elct9620/autonoe/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elct9620%2Fautonoe/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28634785,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-21T04:47:28.174Z","status":"ssl_error","status_checked_at":"2026-01-21T04:47:22.943Z","response_time":86,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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","autonomous-agents","claude-code"],"created_at":"2026-01-04T09:14:49.540Z","updated_at":"2026-01-21T14:01:21.273Z","avatar_url":"https://github.com/elct9620.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Autonoe\n\nAutonomous coding agent orchestrator powered by Claude's Agent SDK.\n\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/elct9620/autonoe)\n[![codecov](https://codecov.io/github/elct9620/autonoe/graph/badge.svg?token=A681DA03X2)](https://codecov.io/github/elct9620/autonoe)\n\n## Inspiration\n\nThis project is inspired by:\n\n- [Autonomous Coding Quickstart](https://github.com/anthropics/claude-quickstarts/tree/main/autonomous-coding) - Anthropic's example of building autonomous coding agents\n- [Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) - Best practices for orchestrating long-running AI agents\n\nAutonoe builds on these concepts by adding:\n\n- **Deliverable-based workflow** - Break work into verifiable units with acceptance criteria\n- **Multi-language support** - Pre-configured profiles for Node.js, Python, Ruby, and Go\n- **Three-layer security** - SDK sandbox, filesystem scope, and command allowlists\n- **Session iteration** - Automatic retry until all deliverables pass\n\n## Quick Start\n\n### Prerequisites\n\n**Default (Recommended):** Uses your Claude Code subscription. Requires [Claude Code](https://claude.ai/code) to be installed and authenticated.\n\n**Alternative:** Use an API key by setting `ANTHROPIC_API_KEY` environment variable. See [Claude Agent SDK documentation](https://github.com/anthropics/claude-agent-sdk) for details.\n\n### Installation\n\n#### Option 1: Pre-built Binary\n\nDownload the latest release from [GitHub Releases](https://github.com/elct9620/autonoe/releases):\n\n| Platform    | File                          |\n| ----------- | ----------------------------- |\n| Linux x64   | `autonoe-linux-x64.tar.gz`    |\n| Linux ARM64 | `autonoe-linux-arm64.tar.gz`  |\n| macOS x64   | `autonoe-darwin-x64.tar.gz`   |\n| macOS ARM64 | `autonoe-darwin-arm64.tar.gz` |\n| Windows x64 | `autonoe-windows-x64.zip`     |\n\n```bash\n# Example for macOS ARM64\ncurl -LO https://github.com/elct9620/autonoe/releases/latest/download/autonoe-darwin-arm64.tar.gz\ntar -xzf autonoe-darwin-arm64.tar.gz\nsudo mv autonoe-darwin-arm64 /usr/local/bin/autonoe\n```\n\n#### Option 2: Docker (Recommended for macOS)\n\nThe SDK sandbox has known issues on macOS. Docker provides a reliable experience.\n\nCreate a `compose.yml` in your project:\n\n```yaml\nservices:\n  cli:\n    image: ghcr.io/elct9620/autonoe/cli:node\n    volumes:\n      - .:/workspace\n    working_dir: /workspace\n    environment:\n      CLAUDE_CODE_OAUTH_TOKEN: ${CLAUDE_CODE_OAUTH_TOKEN:-}\n```\n\n### Usage\n\n1. Create a `SPEC.md` file in your project directory:\n\n```markdown\n# My Project\n\nBuild a simple CLI tool that prints \"Hello, World!\"\n```\n\n2. Run Autonoe:\n\n```bash\n# Using binary\nautonoe run -p /path/to/your/project\n\n# Using Docker\ndocker compose run --rm cli autonoe run\n```\n\n## Docker Options\n\n### Language Profiles\n\nChoose the image tag that matches your project's language:\n\n| Tag      | Description                          |\n| -------- | ------------------------------------ |\n| `base`   | Minimal runtime (git, curl only)     |\n| `node`   | Node.js with npm and Playwright      |\n| `python` | Python with pip and Playwright       |\n| `golang` | Go toolchain with Playwright         |\n| `ruby`   | Ruby with gem/bundler and Playwright |\n\nExample for a Python project:\n\n```yaml\nservices:\n  cli:\n    image: ghcr.io/elct9620/autonoe/cli:python\n    volumes:\n      - .:/workspace\n    working_dir: /workspace\n    environment:\n      CLAUDE_CODE_OAUTH_TOKEN: ${CLAUDE_CODE_OAUTH_TOKEN:-}\n```\n\n### Authentication\n\n| Variable                  | Description                                  |\n| ------------------------- | -------------------------------------------- |\n| `CLAUDE_CODE_OAUTH_TOKEN` | Claude Code subscription token (recommended) |\n| `ANTHROPIC_API_KEY`       | API key for direct billing                   |\n\nCreate a `.env` file (Docker Compose loads it automatically):\n\n```bash\nCLAUDE_CODE_OAUTH_TOKEN=your-oauth-token\n```\n\n## CLI Reference\n\n### Common Options\n\nAll commands share the following options:\n\n| Option             | Short | Description                                   | Default   |\n| ------------------ | ----- | --------------------------------------------- | --------- |\n| `--project-dir`    | `-p`  | Project directory                             | cwd       |\n| `--max-iterations` | `-n`  | Maximum coding sessions                       | unlimited |\n| `--max-retries`    |       | Maximum retries on session error              | 3         |\n| `--model`          | `-m`  | Claude model to use                           | -         |\n| `--debug`          | `-d`  | Show debug output                             | false     |\n| `--wait-for-quota` |       | Wait for quota reset instead of exiting       | false     |\n| `--thinking`       |       | Enable extended thinking mode (budget tokens) | 8192      |\n\n### run Command\n\nImplements deliverables from SPEC.md.\n\n```bash\nautonoe run [options]\n```\n\n**Additional Options:**\n\n| Option                | Short | Description                           | Default |\n| --------------------- | ----- | ------------------------------------- | ------- |\n| `--no-sandbox`        |       | Disable SDK sandbox (not recommended) | false   |\n| `--allow-destructive` | `-D`  | Enable rm/mv with path validation     | false   |\n\n### sync Command\n\nSynchronizes SPEC.md with status.json and verifies existing implementation.\n\n```bash\nautonoe sync [options]\n```\n\nUses common options only. This is a **read-only operation** that does not modify project files (except `.autonoe/status.json` and `.autonoe-note.md`).\n\n## How It Works\n\nAutonoe provides two commands: `run` for implementation and `sync` for verification.\n\n### run Command\n\nImplements deliverables from SPEC.md in a session loop:\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│                          run Session Loop                           │\n├─────────────────────────────────────────────────────────────────────┤\n│                                                                     │\n│  ┌──────────────────┐                  ┌──────────────────┐        │\n│  │ Phase 1:         │                  │ Phase 2:         │        │\n│  │ Initialization   │─────────────────▶│ Coding           │        │\n│  │                  │                  │                  │        │\n│  │ - Read SPEC.md   │  (status.json    │ - Implement      │        │\n│  │ - Create         │   created)       │ - Test \u0026 Verify  │        │\n│  │   deliverables   │                  │ - Mark status    │        │\n│  └──────────────────┘                  └────────┬─────────┘        │\n│                                                 │                   │\n│                                                 ▼                   │\n│                                  ┌──────────────────────────┐      │\n│                                  │ All deliverables passed? │      │\n│                                  └─────────────┬────────────┘      │\n│                                       Yes      │      No           │\n│                                        ▼       │       ▼           │\n│                                      Done      │  ┌────────────┐   │\n│                                                │  │ Continue?  │   │\n│                                                │  └─────┬──────┘   │\n│                                                │        │          │\n│                                                │   Yes  │  No      │\n│                                                │    ▼   │   ▼      │\n│                                                │  Next  │  Exit    │\n│                                                │ session│          │\n│                                                └────────┘          │\n└─────────────────────────────────────────────────────────────────────┘\n\nExit conditions: max iterations, all blocked, quota exceeded, max retries\n```\n\n**Phase 1: Initialization**\n\n- Reads your `SPEC.md` file\n- Creates deliverables with acceptance criteria\n- Stores status in `.autonoe/status.json`\n\n**Phase 2: Coding**\n\n- Implements each deliverable\n- Runs tests and verification\n- Marks deliverables as passed/failed\n- Continues until all deliverables pass or max iterations reached\n\n### sync Command\n\nSynchronizes SPEC.md changes and verifies existing implementation (**read-only**):\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│                         sync Session Loop                           │\n├─────────────────────────────────────────────────────────────────────┤\n│                                                                     │\n│  ┌──────────────────┐                  ┌──────────────────┐        │\n│  │ Phase 1:         │                  │ Phase 2:         │        │\n│  │ Sync             │─────────────────▶│ Verify           │        │\n│  │                  │                  │                  │        │\n│  │ - Read SPEC.md   │  (status.json    │ - Run tests      │        │\n│  │ - Create/Update  │   updated)       │ - Validate code  │        │\n│  │   deliverables   │                  │ - Mark verified  │        │\n│  └──────────────────┘                  └────────┬─────────┘        │\n│                                                 │                   │\n│                                                 ▼                   │\n│                                ┌────────────────────────────┐      │\n│                                │ All deliverables verified? │      │\n│                                └─────────────┬──────────────┘      │\n│                                       Yes    │      No             │\n│                                        ▼     │       ▼             │\n│                                      Done    │   Continue          │\n└─────────────────────────────────────────────────────────────────────┘\n\nDoes NOT modify project files (only .autonoe/status.json and .autonoe-note.md)\n```\n\n**Phase 1: Sync**\n\n- Reads your `SPEC.md` file\n- Creates new deliverables or marks removed ones as deprecated\n- Updates `.autonoe/status.json`\n\n**Phase 2: Verify**\n\n- Runs tests and validation\n- Confirms deliverable status matches implementation\n- Marks each deliverable as verified\n\n### Deliverable Status\n\nEach deliverable tracks progress with three states:\n\n| Status    | Meaning                                |\n| --------- | -------------------------------------- |\n| `pending` | Not yet completed                      |\n| `passed`  | All acceptance criteria verified       |\n| `blocked` | Cannot proceed (dependency/constraint) |\n\nDeliverables removed from SPEC.md are marked with `deprecatedAt` timestamp and excluded from termination evaluation.\n\n### Exit Conditions\n\n| Condition             | run | sync |\n| --------------------- | --- | ---- |\n| All achievable passed | ✓   | -    |\n| All verified          | -   | ✓    |\n| All blocked           | ✓   | ✓    |\n| Max iterations        | ✓   | ✓    |\n| Max retries           | ✓   | ✓    |\n| Quota exceeded        | ✓   | ✓    |\n\n## Configuration\n\nCreate `.autonoe/agent.json` to customize behavior:\n\n```json\n{\n  \"profile\": [\"node\", \"python\"],\n  \"allowCommands\": {\n    \"base\": [\"make\"],\n    \"run\": [\"docker\", \"custom-cli\"],\n    \"sync\": [\"shellcheck\"]\n  },\n  \"allowPkillTargets\": [\"custom-server\"],\n  \"permissions\": {\n    \"allow\": [\"WebFetch(https://api.example.com/*)\"]\n  },\n  \"allowedTools\": [\"Task\", \"WebSearch\"],\n  \"mcpServers\": {\n    \"custom-tool\": {\n      \"command\": \"npx\",\n      \"args\": [\"custom-mcp-server\"]\n    }\n  }\n}\n```\n\n### Configuration Options\n\n| Field               | Type                         | Description                                |\n| ------------------- | ---------------------------- | ------------------------------------------ |\n| `profile`           | `string \\| string[]`         | Language profiles to enable (default: all) |\n| `allowCommands`     | `string[] \\| TieredCommands` | Additional bash commands (see below)       |\n| `allowPkillTargets` | `string[]`                   | Additional processes that can be killed    |\n| `permissions.allow` | `string[]`                   | SDK permission rules                       |\n| `allowedTools`      | `string[]`                   | Additional SDK tools to enable             |\n| `mcpServers`        | `object`                     | Custom MCP servers                         |\n\n### allowCommands Structure\n\nCommands can be specified per-command or shared:\n\n| Key    | Applies to   | Example                  |\n| ------ | ------------ | ------------------------ |\n| `base` | run and sync | `\"base\": [\"make\"]`       |\n| `run`  | run only     | `\"run\": [\"docker\"]`      |\n| `sync` | sync only    | `\"sync\": [\"shellcheck\"]` |\n\nLegacy `string[]` format is treated as `{ run: [...] }` for backward compatibility.\n\n### Language Profiles\n\n| Profile  | Includes                                     |\n| -------- | -------------------------------------------- |\n| `node`   | node, npm, bun, yarn, pnpm, vite, next, etc. |\n| `python` | python, pip, uv, pytest, django, flask, etc. |\n| `ruby`   | ruby, gem, bundle, rails, rspec, etc.        |\n| `go`     | go, gofmt, golangci-lint, etc.               |\n\n## Custom Instructions\n\nOverride the default agent instructions by creating files in `.autonoe/`:\n\n| File                      | Command | Purpose                                        |\n| ------------------------- | ------- | ---------------------------------------------- |\n| `.autonoe/initializer.md` | run     | First session: read SPEC, create deliverables  |\n| `.autonoe/coding.md`      | run     | Subsequent sessions: implement and verify      |\n| `.autonoe/sync.md`        | sync    | First session: parse SPEC, update deliverables |\n| `.autonoe/verify.md`      | sync    | Subsequent sessions: validate implementation   |\n\n### Instruction Selection\n\n**run command:**\n\n1. First session (no `.autonoe/status.json`): Uses `initializer.md`\n2. Subsequent sessions: Uses `coding.md`\n\n**sync command:**\n\n1. First session: Uses `sync.md`\n2. Subsequent sessions: Uses `verify.md`\n\n### Override Priority\n\n```\n.autonoe/{name}.md  →  (if exists) use custom\n                    →  (if not) use built-in default\n```\n\n### Example: Custom Initializer\n\n```bash\nmkdir -p .autonoe\n\ncat \u003e .autonoe/initializer.md \u003c\u003c 'EOF'\n# Custom Initialization\n\nYour custom instructions here...\n\n## Required Steps\n1. Read SPEC.md\n2. Create deliverables with acceptance criteria\n...\nEOF\n```\n\nCustom instructions completely replace the defaults (no merging).\n\n### Agent Notes\n\nThe agent may create `.autonoe-note.md` to persist observations between sessions.\nThis file is auto-generated and should not be manually edited.\n\n## Security Model\n\nAutonoe implements three layers of security:\n\n```\n┌─────────────────────────────────────────────────────┐\n│              Security Layers                         │\n├─────────────────────────────────────────────────────┤\n│  Layer 1: SDK Sandbox                               │\n│  ├── OS-level process isolation                     │\n│  └── Filesystem/network containment                 │\n├─────────────────────────────────────────────────────┤\n│  Layer 2: Filesystem Scope                          │\n│  └── Read/Write limited to project directory        │\n├─────────────────────────────────────────────────────┤\n│  Layer 3: PreToolUse Hooks                          │\n│  ├── BashSecurity: Command allowlist                │\n│  └── AutonoeProtection: Block writes to .autonoe/   │\n└─────────────────────────────────────────────────────┘\n```\n\n## Sandbox Limitations\n\nThe Claude Agent SDK sandbox has platform-specific limitations:\n\n| Limitation                           | Workaround                                    |\n| ------------------------------------ | --------------------------------------------- |\n| macOS support unstable               | Use Docker                                    |\n| Linux ARM64 browser install fails    | Disable sandbox, use `npx playwright install` |\n| Cannot detect pre-installed browsers | Install browser at runtime via npx            |\n\n### Docker (Recommended)\n\nDocker images disable the sandbox by default (`AUTONOE_NO_SANDBOX=1`) for maximum compatibility. Browser automation works reliably across all platforms.\n\nFor browser automation, add to your `SPEC.md`:\n\n```markdown\n## Prerequisites\n\nBefore browser testing, install Chromium:\nnpx playwright install --with-deps chromium\n```\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│  apps/cli (Presentation)                                        │\n│    CLI commands, argument parsing, output formatting            │\n└─────────────────────────────────────────────────────────────────┘\n              │                                       │\n              ▼                                       ▼\n┌─────────────────────────────────┐  ┌─────────────────────────────────┐\n│       packages/core             │  │  packages/agent                 │\n│  SessionRunner, Session         │  │  ClaudeAgentClient (SDK wrapper)│\n│  BashSecurity, Configuration    │  │  Converters (SDK ↔ Domain)      │\n│  Types (NO external deps)       │  │  Depends on @autonoe/core       │\n└─────────────────────────────────┘  └─────────────────────────────────┘\n```\n\n| Package          | Description                                                      |\n| ---------------- | ---------------------------------------------------------------- |\n| `@autonoe/cli`   | Entry point, CLI argument parsing                                |\n| `@autonoe/core`  | Domain types, session orchestration (zero external dependencies) |\n| `@autonoe/agent` | Claude Agent SDK wrapper                                         |\n\n## Development\n\n### Commands\n\n```bash\nbun run check          # Type checking\nbun run format         # Format code with Prettier\nbun run compile        # Compile to single executable\n```\n\n### Testing\n\n```bash\nbun run test                       # Run all tests\nbun run test --project core        # Run core package tests\nbun run test --project agent       # Run agent package tests\nbun run test --coverage            # Run with coverage report\nmake test-integration              # Run integration tests (requires Docker)\n```\n\n### Docker\n\n```bash\n# Build the CLI image\ndocker compose build\n\n# Run CLI in container\ndocker compose run --rm cli autonoe run\n\n# Build specific target (base, node, python, golang, ruby)\ndocker build --target python -f apps/cli/Dockerfile .\n```\n\n## License\n\n[Apache License 2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felct9620%2Fautonoe","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felct9620%2Fautonoe","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felct9620%2Fautonoe/lists"}