{"id":51723157,"url":"https://github.com/arjia-labs/clu","last_synced_at":"2026-08-05T22:00:36.676Z","repository":{"id":362264611,"uuid":"1249836309","full_name":"Arjia-Labs/clu","owner":"Arjia-Labs","description":"Local-first SQLite issue tracker for coordinating AI coding agents — atomic claim, dependency graphs, workflows \u0026 checkpoints, audit log. No daemon, no network.","archived":false,"fork":false,"pushed_at":"2026-07-17T07:20:45.000Z","size":8546,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-25T10:18:42.646Z","etag":null,"topics":["agent-orchestration","ai-agents","cli","developer-tools","go","golang","issue-tracker","local-first","multi-agent","sqlite","task-management","workflow-engine"],"latest_commit_sha":null,"homepage":"https://arjia-labs.github.io/clu/","language":"Go","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/Arjia-Labs.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":"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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-26T04:36:43.000Z","updated_at":"2026-07-17T07:20:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Arjia-Labs/clu","commit_stats":null,"previous_names":["arjia-labs/clu"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Arjia-Labs/clu","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Arjia-Labs%2Fclu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Arjia-Labs%2Fclu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Arjia-Labs%2Fclu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Arjia-Labs%2Fclu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Arjia-Labs","download_url":"https://codeload.github.com/Arjia-Labs/clu/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Arjia-Labs%2Fclu/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36322586,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-08-05T02:00:06.619Z","response_time":104,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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-orchestration","ai-agents","cli","developer-tools","go","golang","issue-tracker","local-first","multi-agent","sqlite","task-management","workflow-engine"],"created_at":"2026-07-17T15:00:32.875Z","updated_at":"2026-08-05T22:00:36.657Z","avatar_url":"https://github.com/Arjia-Labs.png","language":"Go","funding_links":[],"categories":["Harnesses \u0026 orchestration"],"sub_categories":["Agent infrastructure"],"readme":"\u003ch1 align=\"center\"\u003eclu\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/header.jpg\" alt=\"clu — agent-coordination issue tracker\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003e🤖 SQLite-backed issue tracker for coordinating AI coding agents on a single machine.\u003c/em\u003e\u003cbr\u003e\n  \u003cem\u003eNamed after Tron's \u003cstrong\u003eC\u003c/strong\u003eodified \u003cstrong\u003eL\u003c/strong\u003eikeness \u003cstrong\u003eU\u003c/strong\u003etility.\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/arjia-labs/clu/actions\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/arjia-labs/clu/ci.yml?branch=main\u0026label=build\u0026style=flat-square\u0026logo=github\" alt=\"Build status\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://goreportcard.com/report/github.com/arjia-labs/clu\"\u003e\u003cimg src=\"https://goreportcard.com/badge/github.com/arjia-labs/clu?style=flat-square\" alt=\"Go report card\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pkg.go.dev/github.com/arjia-labs/clu\"\u003e\u003cimg src=\"https://img.shields.io/badge/pkg.go.dev-reference-007d9c?style=flat-square\u0026logo=go\u0026logoColor=white\" alt=\"Go reference\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/go-1.26%2B-00ADD8?style=flat-square\u0026logo=go\u0026logoColor=white\" alt=\"Go 1.26+\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/sqlite-pure_go-003B57?style=flat-square\u0026logo=sqlite\u0026logoColor=white\" alt=\"SQLite (pure Go)\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/license-MIT-blue?style=flat-square\" alt=\"MIT licensed\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/CGo-free-success?style=flat-square\" alt=\"No CGo\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/network-none-lightgrey?style=flat-square\" alt=\"No network\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://arjia-labs.github.io/clu/\"\u003e\u003cimg src=\"https://img.shields.io/badge/%F0%9F%93%96_Read_the_docs-arjia--labs.github.io%2Fclu-007d9c?style=for-the-badge\" alt=\"Documentation\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://arjia-labs.github.io/clu/\"\u003e\u003cstrong\u003eDocs\u003c/strong\u003e\u003c/a\u003e ·\n  \u003ca href=\"#-quickstart\"\u003e\u003cstrong\u003eQuickstart\u003c/strong\u003e\u003c/a\u003e ·\n  \u003ca href=\"#-multi-agent-setup\"\u003e\u003cstrong\u003eMulti-agent\u003c/strong\u003e\u003c/a\u003e ·\n  \u003ca href=\"#-bulk-graphs-clu-batch\"\u003e\u003cstrong\u003eBulk graphs\u003c/strong\u003e\u003c/a\u003e ·\n  \u003ca href=\"#-workflows\"\u003e\u003cstrong\u003eWorkflows\u003c/strong\u003e\u003c/a\u003e ·\n  \u003ca href=\"AGENTS.md\"\u003e\u003cstrong\u003eAgent guide\u003c/strong\u003e\u003c/a\u003e ·\n  \u003ca href=\"#-design-notes\"\u003e\u003cstrong\u003eDesign\u003c/strong\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## 🤔 Why?\n\nWhen you run more than one AI coding session against the same project, they need a shared, durable place to:\n\n- 🤝 pick up work without stepping on each other (atomic claim),\n- 📝 record what they tried, what worked, what didn't,\n- 🚦 gate risky steps behind human approval,\n- 🔓 surface what's unblocked vs. waiting on something else.\n\n`clu` is that place. A small, fast, single-binary CLI backed by a local SQLite database. **No daemon, no server, no account, no network.**\n\n## ✨ Highlights\n\n| | |\n|---|---|\n| 📦 **Single binary, pure Go** | SQLite via `modernc.org/sqlite` — no CGo, no system libs. |\n| 💾 **Local-first** | One file: `.clu/data.sqlite`. Commit `config.yaml`, gitignore the DB. |\n| ⚡ **Atomic claim** | `UPDATE … RETURNING` with subquery — racing agents get different issues. |\n| 🎯 **Capability routing** | Agents declare capabilities in `config.yaml`; `cap:foo` labels flow to matching agents. |\n| 🕸️ **Bulk graph instantiation** | `clu batch` turns one JSON doc into a whole validated graph (thousands of issues + deps) in one transaction — generate it with any script. |\n| 🌊 **Cascading cancel** | `clu cancel \u003cid\u003e` walks the dep graph forward and cancels the whole tail. |\n| 🏁 **Milestones \u0026 phases** | `milestone` issues auto-close when their dependencies do — self-completing umbrellas and automatic phase boundaries. |\n| 🧾 **Audit log** | Every write is recorded; `clu history \u003cid\u003e` and `clu log` show who did what, when. |\n| 🧠 **Context inheritance** | `clu claim \u003cid\u003e --context` prints the upstream chain (notes + comments) so an agent inherits what was done before. |\n| 🚀 **Agent launcher** | `clu agent start \u003cname\u003e` spawns a configured agent (command + layered prompts) and heartbeats it. |\n| 📋 **Workflow templates** | YAML graphs of issues + deps with optional human-approval checkpoints. |\n| 🔒 **Named locks + mailbox** | TTL'd `clu lock` for shared resources; `clu ping`/`clu inbox` for fire-and-forget inter-agent messages. |\n| 🖥️ **Web UI** | `clu web` — a local dashboard: list, kanban, dependency graph, approvals. |\n| 🧾 **JSON everywhere** | Every command takes `--json` and emits exactly one JSON value to stdout. |\n| 🌿 **Branchless sync** *(experimental)* | `clu sync` stores issues on a dedicated git ref (`refs/clu/store`) — branch-independent, no conflicts with code, syncs across clones. [Details](docs/content/docs/sync.mdx). |\n| 🔒 **No network** | No telemetry, no cloud, no account. Sharing is opt-in over *your own* git remote. |\n\n## 🖥️ Web UI\n\n`clu web` serves a local dashboard (default `:5757`) over the same SQLite file — no extra config, no separate API to run.\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"50%\"\u003e\u003cimg src=\"assets/web-board.png\" alt=\"Kanban board grouped by status with assignee avatars and in-progress timers\"\u003e\u003cbr\u003e\u003csub\u003e\u003cb\u003eBoard\u003c/b\u003e — kanban by status, with avatars and how long each task has been in progress.\u003c/sub\u003e\u003c/td\u003e\n    \u003ctd width=\"50%\"\u003e\u003cimg src=\"assets/web-list.png\" alt=\"Issue list with priority, status and started-at timestamps\"\u003e\u003cbr\u003e\u003csub\u003e\u003cb\u003eList\u003c/b\u003e — every issue with priority, status, and \u003ccode\u003estarted_at\u003c/code\u003e (\"started 3h ago\").\u003c/sub\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"50%\"\u003e\u003cimg src=\"assets/web-approvals.png\" alt=\"Approvals view showing pending checkpoint cards\"\u003e\u003cbr\u003e\u003csub\u003e\u003cb\u003eApprovals\u003c/b\u003e — pending checkpoints with suggested approvers and what they block.\u003c/sub\u003e\u003c/td\u003e\n    \u003ctd width=\"50%\"\u003e\u003cimg src=\"assets/web-detail.png\" alt=\"Issue detail with checkpoint gate and dependency edges\"\u003e\u003cbr\u003e\u003csub\u003e\u003cb\u003eDetail\u003c/b\u003e — status/priority/type controls, the checkpoint gate, and dependency edges.\u003c/sub\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n## 📦 Install\n\n```bash\n# From a clone (installs the CLI + the web UI bundle):\nmake install\n\n# Or, just the CLI:\ngo install github.com/arjia-labs/clu/cmd/clu@latest\n```\n\n`make install` runs `go install` and then `clu web --install`, which\nbuilds the web UI (`pnpm install` + `pnpm build`) and copies the\noutput to `~/.local/share/clu/web` so `clu web` works from any\ndirectory. Skipped silently if pnpm isn't on PATH — the CLI works\nwithout the UI.\n\nAdd `$HOME/go/bin` to your `PATH`. Verify with `clu --help`.\n\n## 🚀 Quickstart\n\n```bash\nmkdir my-project \u0026\u0026 cd my-project\nclu init                                       # 📂 creates .clu/ with DB + config\nclu create -p 1 \"fix the login redirect\"             # → clu-a3f81b\nclu create -d clu-a3f81b \"add tests for the redirect\"  # 🔗 wires the dep atomically\n\nclu ready                                      # 🟢 what's unblocked?\nclu claim --context                            # 🎯 take the next one + see its upstream context\nclu close clu-a3f81b                           # ✅ done → unblocks the tests\nclu ready                                      # 🟢 tests are now ready\n```\n\nThat's the whole core loop. See [`demo.sh`](demo.sh) for an end-to-end exercise, or [`AGENTS.md`](AGENTS.md) for the agent-facing operational guide. From inside an agent session:\n\n```bash\nclu brief\n```\n\nprints the agent guide plus the project's declared agents and who's currently live — pipe it into your agent at session start. 🧠\n\n## 🚦 Status semantics\n\n| status | meaning | downstream effect |\n|---|---|---|\n| 🟢 `open` | not yet started | normal |\n| 🟡 `in_progress` | claimed; an agent is working | normal |\n| ✅ `closed` | done successfully | **unblocks** dependents |\n| ❌ `cancelled` | abandoned | dependents stay blocked (or cascade-cancel) |\n\n`clu cancel \u003cid\u003e` marks the target **and all transitive descendants** as cancelled — the cascade is the whole point of having a status distinct from `closed`. `clu reopen \u003cid\u003e` reverses either terminal state.\n\n```mermaid\nstateDiagram-v2\n    [*] --\u003e open: create\n    open --\u003e in_progress: claim\n    in_progress --\u003e closed: close\n    in_progress --\u003e cancelled: cancel\n    open --\u003e cancelled: cancel\n    closed --\u003e open: reopen\n    cancelled --\u003e open: reopen\n    closed --\u003e [*]\n    note right of closed: unblocks dependents\n    note right of cancelled: cascade-cancels the tail\n```\n\nTwo type-driven behaviours sit on top of the status loop: a **`checkpoint`** issue is a manual gate (stays `checkpoint:pending` until `clu approve`), and a **`milestone`** issue *auto-closes* when all its dependencies close — the self-completing umbrella behind `clu batch --group` and phase boundaries. Issues also carry a `started_at` (set on claim, distinct from `updated`) so `clu show`, the web list, and `doctor`'s stuck-check know how long something's actually been in progress.\n\n## 🤖 Multi-agent setup\n\nDeclare your agents in `.clu/config.yaml`:\n\n```yaml\nid_prefix: clu-\nagents:\n  code-reviewer:\n    description: \"Reviews Go code for correctness and security\"\n    capabilities: [go-review, security-review]\n  doc-writer:\n    description: \"Writes README + docs/ updates\"\n    capabilities: [docs]\n```\n\nThen each agent claims from its own lane:\n\n```bash\nclu claim --agent code-reviewer --wait --heartbeat\n```\n\n`--heartbeat` is opt-in; without it the claim loop doesn't advertise liveness. With it, `clu agent ls` shows who's online and when they were last seen.\n\nCoordinators route work by either **assigning directly** (`clu create -a doc-writer ...`) or **tagging capability** (`clu create --capability docs ...`). Capability-tagged issues in the default lane flow to whichever agent advertises that capability. Use `clu create --label urgent ...` when a normal label should be attached atomically with the new issue.\n\n### 🚀 Launching agents\n\nGive an agent a launch spec in `config.yaml` and start it with one command:\n\n```yaml\nagents:\n  code-reviewer:\n    capabilities: [go-review]\n    command: claude                     # the executable to run\n    prompts: [SOUL.md]                  # files under .clu/agents/code-reviewer/\n    startup_prompt: \"Check clu inbox -a code-reviewer, then claim ready work.\"\n```\n\n```bash\nclu agent start code-reviewer          # exec the agent, heartbeating while it runs\nclu agent start code-reviewer --print  # just show the assembled command\n```\n\nAny `*.md` in `.clu/agents/_shared/` is prepended to **every** agent (a common `AGENTS.md` / `AUTONOMY.md` lives in one place, not copied per agent); the agent's own prompts layer on top. clu stays runtime-agnostic — `command` can be `claude`, `codex`, or anything.\n\n### 🧠 Inheriting context\n\nWhen an agent picks up a dependent task, `--context` walks the upstream chain and prints each prerequisite's description, notes, and comments — the story of what was done before:\n\n```bash\nclu claim \u003cid\u003e --context        # on claim\nclu show \u003cid\u003e --context         # any time\n```\n\n### 👁️ Watching for work (the killer combo)\n\nIn Claude Code, point the Monitor tool at `clu ready --watch -a \u003cyour-name\u003e` and you've got a push-style task feed: clu suppresses unchanged ticks, Monitor turns each new state into one notification. **No polling loops, no `while true`, no `diff` against `seen`.**\n\n```\nMonitor: clu ready --watch -a code-reviewer\n```\n\nSee [AGENTS.md](AGENTS.md) for the full pattern.\n\n## 🕸️ Bulk graphs (`clu batch`)\n\n`clu run` is for hand-authored YAML. When you want to **generate** work —\nimport a backlog, fan out a migration across modules, or build a thousand\ninterdependent tasks — produce a JSON document with any tool and pipe it to\n`clu batch`. clu validates the whole graph (acyclic, every reference\nresolves, fields valid) and writes it in **one transaction**: a single bad\nentry aborts everything, so you never get a half-built graph.\n\n```bash\ngenerate-graph | clu batch --dry-run                 # validate + stats, write nothing\ngenerate-graph | clu batch --group \"Auth rollout\"    # commit under a self-completing umbrella\n```\n\nThe contract is just JSON — an array of issues that reference each other by\nlocal **alias**:\n\n```json\n[\n  {\"alias\": \"design\", \"title\": \"Design auth\", \"priority\": 1},\n  {\"alias\": \"impl\",   \"title\": \"Implement auth\", \"needs\": [\"design\"], \"capabilities\": [\"go\"]},\n  {\"alias\": \"gate\",   \"title\": \"Approve release\", \"needs\": [\"impl\"], \"checkpoint\": {\"approvers\": [\"alice\"]}},\n  {\"alias\": \"ship\",   \"title\": \"Ship\", \"needs\": [\"gate\"]}\n]\n```\n\nRun **`clu batch --docs`** for the full field reference. Highlights:\n\n- **`needs`** takes aliases *or* existing real issue IDs — so a generated subgraph can hang off the committed graph.\n- **`checkpoint`** makes an issue a manual approval gate (same as a `clu run` checkpoint).\n- **`key`** (e.g. `\"linear:ENG-123\"`) makes re-running **idempotent** — `--on-existing skip` (default) won't duplicate it; `--on-existing update` re-syncs its fields. Perfect for a recurring import:\n\n  ```bash\n  linear issue query --json | node examples/generators/linear-todo.js | clu batch --on-existing update\n  ```\n\nThis is the **generation / instantiation split**: any language emits the graph (loops, conditionals, computed fan-out — things a static template can't do); clu owns validation and atomic instantiation. See [`examples/generators/`](examples/generators/) for a zero-dependency JS helper (`clu.js`) with a `phase()` builder, plus runnable examples (feature rollout, release train, phased migration, Linear import).\n\n## 📋 Workflows\n\nDrop a YAML template into `.clu/templates/`:\n\n```yaml\nname: release\nvars:\n  version: { required: true, pattern: '^\\d+\\.\\d+\\.\\d+$' }\nsteps:\n  - id: build\n    title: \"Build {{version}}\"\n  - id: test\n    title: \"Test {{version}}\"\n    needs: [build]\n  - id: approve\n    type: checkpoint                          # 🚦 human gate\n    title: \"Approve {{version}} for prod\"\n    wait: { approval: [alice, bob] }\n    needs: [test]\n  - id: deploy\n    title: \"Deploy {{version}}\"\n    needs: [approve]\n```\n\n```bash\nclu run release -v version=1.2.3   # → parent + 4 children + deps in one shot\n```\n\nAgents drive it by claiming `ready` issues as each step closes; humans clear checkpoint gates via `clu approve \u003cid\u003e`. Failing a checkpoint cascade-cancels the rest of the run. See [`demo-workflow.sh`](demo-workflow.sh) for the full demo.\n\n\u003e `clu batch` is the programmable superset of `clu run` — same checkpoints and grouping, but the graph comes from code instead of a YAML template.\n\n## 🧾 Audit \u0026 history\n\nEvery write is recorded in an append-only event log:\n\n```bash\nclu history \u003cid\u003e                      # full timeline of one issue (who/what/when)\nclu log --kind claimed --since 24h    # global stream, filterable by actor/kind/issue/since\n```\n\nThe actor is the resolved `--agent` (or `$USER`); payloads record just the changed fields. The log is local — it's not part of `clu export` (which carries portable state, not history).\n\n## 🖥️ Web UI\n\n```bash\nclu web        # serves a local dashboard (default :5757)\n```\n\nA read/write dashboard: filterable issue list, kanban board, dependency graph for a run, and an approvals queue for pending checkpoints. Backed by the same store via an in-process REST API (`clu http` exposes that API standalone).\n\n## 🤝 Coordination primitives\n\nBeyond the issue graph, for things that don't fit a ticket:\n\n```bash\nclu lock deploy --ttl 1h -- ./deploy.sh prod   # TTL'd named lock; auto-released, leak-proof\nclu ping code-reviewer \"PR #412 ready\"          # fire-and-forget message (TTL'd, off the work log)\nclu inbox -a code-reviewer                       # read your messages\nclu worktree add feature-x --bootstrap           # git worktree + project-defined setup\nclu sync push --remote origin                    # publish issues to a branch-independent git ref (experimental)\n```\n\n`clu sync` (experimental) keeps the tracker on a dedicated `refs/clu/store` ref —\nso any checkout sees the same issues, writes never collide with code commits, and\na teammate's clone can `clu sync pull --remote origin` to get the backlog without\nthe DB ever being committed. See [the sync docs](docs/content/docs/sync.mdx).\n\n## 📁 Layout\n\n```\ncmd/clu/                 ⌨️  entrypoint\ninternal/cli/            🧩 one file per kong subcommand\ninternal/store/          💾 SQLite layer, split by domain\n  ├── models.go            bun model types\n  ├── migrations.go        manual migrations (PRAGMA user_version)\n  ├── issues.go            create/get/close/reopen/cancel/update\n  ├── claim.go             ready/claim atomic queries\n  ├── deps.go              dependency edges + cycle detection\n  ├── batch.go             validated bulk graph instantiation\n  ├── milestone.go         auto-close cascade\n  ├── events.go            append-only audit log\n  ├── context.go           ancestor-context walk\n  └── …                    labels, comments, kv, cron, agents, locks, mailbox, doctor\ninternal/workflow/       📋 YAML template loader + planner\ninternal/http/           🌐 REST API (backs the web UI / `clu http`)\ninternal/config/         ⚙️  config.yaml parsing\nweb/clu-web/             🖥️  TanStack Start web dashboard\nexamples/generators/     🕸️  codemode graph generators for `clu batch`\n.clu/                    📂 per-project storage (DB, config, templates, agents/)\n```\n\n## 🧠 Design notes\n\n```mermaid\nflowchart TB\n    subgraph clients[\"Clients\"]\n        cli[\"clu CLI\u003cbr/\u003e(Kong)\"]\n        agents[\"AI agents\u003cbr/\u003e(claim · comment · close)\"]\n        batch[\"generators\u003cbr/\u003e(node script | clu batch)\"]\n    end\n    subgraph core[\"clu binary\"]\n        cmds[\"internal/cli\u003cbr/\u003eone file per command\"]\n        http[\"internal/http\u003cbr/\u003eREST API\"]\n        store[\"internal/store\u003cbr/\u003eBun + sqlitedialect\"]\n        wf[\"internal/workflow\u003cbr/\u003eYAML planner\"]\n    end\n    web[\"web/clu-web\u003cbr/\u003eTanStack dashboard\"]\n    db[(\".clu/data.sqlite\u003cbr/\u003esingle file, pure-Go driver\")]\n\n    agents --\u003e cli\n    cli --\u003e cmds\n    batch --\u003e cmds\n    cmds --\u003e store\n    wf --\u003e cmds\n    http --\u003e store\n    web --\u003e http\n    store --\u003e db\n```\n\n- 🪪 **One identity flag.** `-a` / `--agent` is both the lane filter and the actor identity. No `--as` — single-user local tool, the user/agent distinction was deliberately collapsed.\n- 🗄️ **Hand-rolled migrations** via `PRAGMA user_version`. Append-only, never edit an applied migration.\n- 🛠️ **Bun + sqlitedialect** for queries. Raw SQL escape hatches in exactly two places: the atomic claim, and the cancel-cascade CTE.\n- 🎀 **Kong** for the CLI struct, with struct-tag commands and intermixed flags.\n\nThe rationale for each sticky decision lives in [`CLAUDE.md`](CLAUDE.md).\n\n## 🙅 Not in scope\n\n`clu` is deliberately small. It does **not** try to be:\n\n- 🔄 a live, server-backed sync layer with cell-level merge — for sharing across machines there's the experimental [`clu sync`](docs/content/docs/sync.mdx) git ref (manual push/pull over your own remote), not a always-on sync server\n- 📊 a generic project-management tool — no sprints, milestones, OKRs\n- 🔗 a *live* bridge to GitHub / Linear / Jira. (You can still **import** from anything by piping a generated graph to `clu batch`; an idempotent `key` keeps re-runs clean — see [`examples/generators/linear-todo.js`](examples/generators/linear-todo.js).)\n- 🤖 an agent runtime — *you* are the agent; `clu` just gives you somewhere to put the work\n\n## 🤝 Contributing\n\nPRs welcome. Before sending:\n\n```bash\ngo build ./... \u0026\u0026 go test ./...\n./demo.sh \u0026\u0026 ./demo-workflow.sh\n```\n\nSee [`CLAUDE.md`](CLAUDE.md) for code conventions (one file per kong command, sentinel errors per entity, JSON-clean output, etc.).\n\n## 📜 License\n\nMIT — see [LICENSE](LICENSE).\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003eBuilt for the era of many small agents working together. ⚡\u003c/sub\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farjia-labs%2Fclu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farjia-labs%2Fclu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farjia-labs%2Fclu/lists"}