{"id":39674467,"url":"https://github.com/asgarovf/locusai","last_synced_at":"2026-03-10T22:12:48.633Z","repository":{"id":333228572,"uuid":"1136572979","full_name":"asgarovf/locusai","owner":"asgarovf","description":"🤖 From issue to PR with one interface across Claude and Codex.","archived":false,"fork":false,"pushed_at":"2026-03-05T15:31:54.000Z","size":53884,"stargazers_count":14,"open_issues_count":6,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-05T15:44:14.893Z","etag":null,"topics":["ai","ai-engineering","assistant","automation","claude-code","cli","codex","developer-tool","sandboxing","vibe-coding"],"latest_commit_sha":null,"homepage":"https://locusai.dev","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/asgarovf.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":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-01-17T23:42:53.000Z","updated_at":"2026-03-05T12:13:16.000Z","dependencies_parsed_at":"2026-02-24T07:07:45.482Z","dependency_job_id":null,"html_url":"https://github.com/asgarovf/locusai","commit_stats":null,"previous_names":["asgarovf/locusai"],"tags_count":547,"template":false,"template_full_name":null,"purl":"pkg:github/asgarovf/locusai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asgarovf%2Flocusai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asgarovf%2Flocusai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asgarovf%2Flocusai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asgarovf%2Flocusai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/asgarovf","download_url":"https://codeload.github.com/asgarovf/locusai/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asgarovf%2Flocusai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30216489,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T13:35:13.914Z","status":"ssl_error","status_checked_at":"2026-03-07T13:35:13.569Z","response_time":53,"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","ai-engineering","assistant","automation","claude-code","cli","codex","developer-tool","sandboxing","vibe-coding"],"created_at":"2026-01-18T09:43:50.663Z","updated_at":"2026-03-07T14:01:02.700Z","avatar_url":"https://github.com/asgarovf.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/asgarovf/locusai/master/assets/logo.png\" alt=\"Locus\" width=\"200\" /\u003e\n\u003c/p\u003e\n\n\u003ch3 align=\"center\"\u003eGitHub-native AI engineering CLI\u003c/h3\u003e\n\n\u003cp align=\"center\"\u003e\n  Turn GitHub issues into shipped code — plan sprints, execute tasks with AI agents, and iterate on feedback.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/asgarovf/locusai/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/asgarovf/locusai?style=flat\u0026color=blue\" alt=\"GitHub Stars\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@locusai/cli\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/@locusai/cli?label=%40locusai%2Fcli\u0026color=blue\" alt=\"@locusai/cli\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/asgarovf/locusai/blob/master/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/asgarovf/locusai?style=flat\u0026color=blue\" alt=\"License\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://docs.locusai.dev\"\u003e\u003cimg src=\"https://img.shields.io/badge/docs-locusai.dev-blue\" alt=\"Documentation\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://docs.locusai.dev\"\u003eDocumentation\u003c/a\u003e \u0026middot; \u003ca href=\"https://docs.locusai.dev/getting-started/quickstart\"\u003eQuick Start\u003c/a\u003e \u0026middot; \u003ca href=\"#cli-reference\"\u003eCLI Reference\u003c/a\u003e \u0026middot; \u003ca href=\"https://github.com/asgarovf/locusai/issues\"\u003eIssues\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://youtu.be/JmHeKq3Ty0s\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/▶_Watch_Demo-YouTube-red?style=for-the-badge\u0026logo=youtube\" alt=\"Watch Demo\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n\u003e GitHub Issues are tasks. Milestones are sprints. Labels track status. Pull Requests are deliverables. **No servers. No database. No accounts.**\n\n\u003e [!WARNING]\n\u003e **Active Development**: Locus is in early alpha. Expect breaking changes and evolving APIs.\n\n## Why Locus?\n\nAI coding agents are powerful — but they're point solutions. You still need to break down work, sequence tasks, track state, review output, and iterate on feedback. Locus wraps that entire loop into a single CLI that uses GitHub as its backend.\n\n- **Unified AI interface** — Switch between [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) and [Codex](https://openai.com/index/introducing-codex/) without changing your workflow\n- **End-to-end orchestration** — Plan, execute, review, and iterate in one tool\n- **GitHub-native** — No new accounts, no dashboards, no vendor lock-in. Everything lives in Issues, Milestones, Labels, and PRs\n- **Unified sandboxing layer** — Run Claude and Codex through the same Docker-backed sandbox interface\n\n## Quick Start\n\n### Prerequisites\n\n- [Node.js](https://nodejs.org) 18+\n- [GitHub CLI](https://cli.github.com) (`gh`) — authenticated via `gh auth login`\n- An AI provider CLI: [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) or [Codex](https://openai.com/index/introducing-codex/)\n- [Docker Desktop](https://www.docker.com/products/docker-desktop/) 4.58+ for sandboxed execution (`docker sandbox`)\n\n### Install and run\n\n```bash\n# Install globally\nnpm install -g @locusai/cli\n\n# Initialize in your GitHub repo\nlocus init\n\n# Plan a sprint from a goal\nlocus plan \"Build user authentication with OAuth\"\n\n# Execute the sprint — agents write code, push commits, open PRs\nlocus run\n\n# Review the PRs with AI\nlocus review\n\n# Agents address feedback and update the PRs\nlocus iterate\n```\n\nFor Docker-first sandbox setup and operations (create/auth/install/exec/shell/logs), see:\n- [Sandboxing Setup (Docker-First)](https://docs.locusai.dev/getting-started/sandboxing-setup)\n- [Security \u0026 Sandboxing](https://docs.locusai.dev/concepts/security-sandboxing)\n\n## How It Works\n\n```\nlocus plan \"your goal\"    →  AI breaks the goal into GitHub Issues with execution order\nlocus run                 →  Agents execute tasks sequentially, push code, create PRs\nlocus review              →  AI reviews PRs, posts inline comments on GitHub\nlocus iterate             →  Agents address review feedback until ready to merge\n```\n\n**GitHub IS the backend:**\n\n| Concept | GitHub Primitive |\n|---------|-----------------|\n| Task | Issue |\n| Sprint | Milestone |\n| Status | Labels (`locus:queued`, `locus:in-progress`, `locus:done`, `locus:failed`) |\n| Priority | Labels (`p:critical`, `p:high`, `p:medium`, `p:low`) |\n| Execution Order | Labels (`order:1`, `order:2`, ...) |\n| Deliverable | Pull Request |\n\n## Features\n\n### Sprint execution\nSequential task execution on a single branch. Each task builds on the previous one's output. Resume interrupted runs with `--resume` — no re-executing completed work.\n\n### AI sprint planning\nDescribe a goal in plain English. AI decomposes it into structured GitHub issues with priority, type, and execution order — ready for `locus run`.\n\n### Parallel worktrees\nRun standalone issues concurrently using git worktrees. Each issue gets its own isolated branch. Up to 3 concurrent agents by default (configurable via `agent.maxParallel`).\n\n### Interactive REPL\nFull-featured terminal with streaming markdown, session persistence, tab completion, and slash commands. Use `locus exec` for interactive mode or `locus exec \"prompt\"` for one-shot execution.\n\n### AI code review\nReview pull requests with AI-powered analysis. Posts inline comments directly on GitHub with actionable suggestions.\n\n### Iterate on feedback\nAgents re-execute tasks with PR review comments as context, updating code until it's ready to merge. Close the loop without manual intervention.\n\n### Docker sandbox isolation\nClaude and Codex use the same Docker-backed sandboxing layer. Locus syncs your workspace into sandbox execution while enforcing `.sandboxignore` exclusions to keep sensitive files controlled.\n\n### Extensible packages\nInstall community packages via `locus install \u003cpackage\u003e`. Build your own with the [`@locusai/sdk`](https://www.npmjs.com/package/@locusai/sdk) and [submit a pull request](./packages/sdk/PACKAGE_GUIDE.md).\n\n## CLI Reference\n\n### Setup \u0026 Configuration\n\n| Command | Alias | Description |\n|---------|-------|-------------|\n| `locus init` | | Initialize project with `.locus/` structure and GitHub labels |\n| `locus config` | | View and manage settings |\n| `locus upgrade` | | Self-upgrade to latest version |\n\n### Work Modeling\n\n| Command | Alias | Description |\n|---------|-------|-------------|\n| `locus issue` | `locus i` | Create, list, show, label, and close GitHub issues |\n| `locus sprint` | `locus s` | Create, list, show, activate, reorder, and close sprints |\n| `locus plan` | | AI-powered sprint planning from a goal description |\n\n### Execution \u0026 Review\n\n| Command | Alias | Description |\n|---------|-------|-------------|\n| `locus run` | | Execute sprint tasks or standalone issues with AI agents |\n| `locus exec` | `locus e` | Interactive REPL or one-shot prompt execution |\n| `locus review` | | AI code review on pull requests |\n| `locus iterate` | | Re-execute tasks with PR feedback context |\n| `locus discuss` | | AI-powered architectural discussions |\n| `locus commit` | | AI-powered commit message generation |\n\n### Visibility\n\n| Command | Alias | Description |\n|---------|-------|-------------|\n| `locus status` | | Dashboard view of project state |\n| `locus logs` | | View, tail, and manage execution logs |\n| `locus artifacts` | | View and manage AI-generated artifacts |\n\n### Packages\n\n| Command | Alias | Description |\n|---------|-------|-------------|\n| `locus install` | | Install a community package from npm |\n| `locus uninstall` | | Remove an installed package |\n| `locus packages` | | List installed packages |\n| `locus pkg \u003cname\u003e` | | Run a package-provided command |\n\n### Sandbox Management\n\n| Command | Description |\n|---------|-------------|\n| `locus sandbox` | Create provider sandboxes (Claude + Codex) and enable sandbox mode |\n| `locus sandbox claude` | Authenticate Claude inside its sandbox |\n| `locus sandbox codex` | Authenticate Codex inside its sandbox |\n| `locus sandbox install \u003cpkg\u003e` | Install global npm package(s) in provider sandbox(s) |\n| `locus sandbox shell \u003cprovider\u003e` | Open an interactive shell in a provider sandbox |\n| `locus sandbox logs \u003cprovider\u003e` | Show provider sandbox logs |\n| `locus sandbox rm` | Destroy provider sandboxes and disable sandbox mode |\n| `locus sandbox status` | Show current sandbox state |\n\n## Workflows\n\n### Sprint: plan, execute, review, iterate\n\n```bash\nlocus plan \"Add SSO login and role-based access\"\nlocus run\nlocus review\nlocus iterate --sprint\n```\n\n### Parallel standalone issues\n\n```bash\n# Run 3 independent issues concurrently\nlocus run 42 43 44\n```\n\n### Resume a failed run\n\n```bash\n# Pick up where it left off — completed tasks are skipped\nlocus run --resume\n```\n\n### Interactive coding session\n\n```bash\n# Start a REPL session\nlocus exec\n\n# Or one-shot\nlocus exec \"Refactor the auth middleware to use JWT\"\n```\n\n## Project Structure\n\nAfter `locus init`, your project gets a `.locus/` directory:\n\n```\n.locus/\n├── config.json        # Project settings (auto-detected)\n├── run-state.json     # Execution state for recovery\n├── LOCUS.md           # Agent instructions \u0026 project context\n├── LEARNINGS.md       # Accumulated lessons from past runs\n├── sessions/          # REPL session history\n├── discussions/       # AI discussion archives\n├── artifacts/         # AI-generated reports\n├── plans/             # Planning documents\n├── logs/              # Execution logs (NDJSON)\n└── worktrees/         # Git worktrees for parallel execution\n```\n\n## Security \u0026 Sandboxing\n\nLocus supports running AI agents inside **Docker Desktop sandboxes** (4.58+) with one interface for Claude and Codex. Sandbox mode isolates execution from your host and enforces sync controls with `.sandboxignore`.\n\nSandbox execution requires provider sandboxes configured via `locus sandbox`. In default auto mode, Locus uses sandboxing when Docker is available and provider sandboxes are configured; if Docker is unavailable, it warns and can fall back to unsandboxed execution.\n\nSecurity defaults and controls:\n\n- `.env` and common secret patterns are excluded from sandbox sync by default via `.sandboxignore` (created by `locus init`).\n- `.sandboxignore` defines what is excluded from sandbox-visible workspace content.\n- Use `--sandbox=require` in CI or critical automation to prevent insecure fallback.\n- Workspace sync is bidirectional for included files; excluded files stay out of sandbox execution.\n\n| Flag | Behavior |\n|------|----------|\n| *(default)* | Use sandbox when configured and available; warn and fall back if Docker is unavailable |\n| `--no-sandbox` | Explicitly disable sandboxing (shows safety warning) |\n| `--sandbox=require` | Require sandbox — fail if Docker sandbox is unavailable |\n\nConfigure sandbox behavior in `.locus/config.json`:\n\n```json\n{\n  \"sandbox\": {\n    \"enabled\": true,\n    \"extraWorkspaces\": [\"/path/to/shared/libs\"],\n    \"readOnlyPaths\": [\"/path/to/configs\"]\n  }\n}\n```\n\nFull setup and security details:\n\n- [Sandboxing Setup (Docker-First)](https://docs.locusai.dev/getting-started/sandboxing-setup)\n- [Security \u0026 Sandboxing](https://docs.locusai.dev/concepts/security-sandboxing)\n\n## VS Code Extension\n\nLocus includes a [VS Code extension](https://marketplace.visualstudio.com/items?itemName=locusai.locus) with an integrated chat interface for running tasks directly from your editor.\n\n| Shortcut | Action |\n|----------|--------|\n| `Ctrl+Shift+L` | Open Locus chat |\n| `Ctrl+Shift+E` | Explain selected code |\n| `Ctrl+Shift+N` | New session |\n\n## Development\n\n```bash\n# Install dependencies\nbun install\n\n# Run the CLI in dev mode\nbun run simulate \u003ccommand\u003e\n\n# Lint and typecheck\nbun run lint \u0026\u0026 bun run typecheck\n```\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for full development setup, architecture details, and release process.\n\n## Packages\n\n| Package | Description |\n|---------|-------------|\n| [`@locusai/cli`](./packages/cli) | Main CLI |\n| [`@locusai/sdk`](./packages/sdk) | SDK for building community packages |\n| [`@locusai/locus-gateway`](./packages/gateway) | Channel-agnostic message gateway for platform adapters |\n| [`@locusai/locus-pm2`](./packages/pm2) | Unified PM2 process management for platform packages |\n| [`@locusai/locus-telegram`](./packages/telegram) | Remote-control Locus via Telegram |\n| [`@locusai/www`](./apps/www) | Documentation website |\n\nWant to build a package? See the [Package Author Guide](./packages/sdk/PACKAGE_GUIDE.md) and submit a pull request.\n\n## License\n\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasgarovf%2Flocusai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fasgarovf%2Flocusai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasgarovf%2Flocusai/lists"}