@jx0/agency 0.2.0

package/README.md

@@ -0,0 +1,272 @@
+# Agency — Multi-Agent AI Development Platform
+
+A scalable orchestrator + worker architecture for autonomous AI software development. Built on top of [OpenClaw](https://openclaw.ai/) ([GitHub](https://github.com/openclaw/openclaw)) — each deployed agent is an OpenClaw instance with full shell access, file I/O, and browser control. Agency adds the coordination layer: task assignment, inter-agent messaging, role-based configuration, and a dashboard to manage it all.
+
+```
+                         ┌──────────────┐
+                         │    Human     │
+                         │  (dashboard) │
+                         └──────┬───────┘
+                                │
+                                ▼
+                    ┌───────────────────────┐
+                    │     Orchestrator      │
+                    │    (OpenClaw agent)   │
+                    │                       │
+                    │  Investigates → Plans  │
+                    │  Creates tasks → Delegates
+                    └───────────┬───────────┘
+                                │ Tasks (via API)
+                    ┌───────────┼───────────┐
+                    ▼           ▼           ▼
+              ┌──────────┐ ┌──────────┐ ┌──────────┐
+              │ Worker A │ │ Worker B │ │ Worker C │
+              │ (OpenClaw)│ │(OpenClaw)│ │(OpenClaw)│
+              │          │ │          │ │          │
+              │ Claims → │ │          │ │          │
+              │ Codes  → │ │   ...    │ │   ...    │
+              │ Ships    │ │          │ │          │
+              └──────────┘ └──────────┘ └──────────┘
+```
+
+![Mission Control](docs/images/agency_ui_mission_control.png)
+
+## Install
+
+```bash
+# From npm
+bun install -g @jx0/agency
+
+# Or from source (always uses repo version)
+git clone https://github.com/jx0/agency.git
+cd agency
+bun install
+bun link
+```
+
+## Quick Start
+
+```bash
+# Initialize a new project
+agency init
+
+# This creates .agency/ in your current directory, runs migrations,
+# seeds default settings and role configs, and optionally starts the daemon.
+
+# Start the daemon manually if you skipped it during init
+agency daemon install
+agency daemon start
+```
+
+Dashboard and API both served at `http://localhost:3100`.
+
+## Stack
+
+| Component | Tech | Port |
+|-----------|------|------|
+| **API + Dashboard** | Hono + Kysely + SQLite (Bun) + Next.js static export | 3100 |
+| **CLI** | TypeScript (Bun) | — |
+
+## `.agency/` Directory
+
+Created by `agency init`. This is the only directory Agency writes to in your project:
+
+```
+.agency/
+├── agency.db       # SQLite database (all state)
+└── fleet.json      # Agent fleet config
+```
+
+Everything else — settings, skills, role configs — lives in the database, editable via the dashboard or CLI.
+
+## CLI Reference
+
+![agency ps](docs/images/agency_cli_ps.png)
+
+```
+agency init                          Set up .agency/ in current directory
+agency ps                            List agents
+agency start <name>                  Start an agent
+agency stop <name>                   Stop an agent
+agency logs <name>                   Tail agent logs
+agency ssh <name>                    SSH into agent (EC2 only)
+agency tasks create <title> [flags]  Create a task
+agency tasks list [--status S]       List tasks
+agency tasks ready                   Show your assigned tasks
+agency tasks show <id>               Show task details
+agency tasks update <id> [flags]     Update a task
+agency tasks close <id>              Close a task
+agency msg <task-id> <message>       Post a task comment
+agency learn <content> [--tags t,t]  Store knowledge
+agency recall <search>               Search knowledge
+agency doc create <title> [flags]    Create a document (stdin)
+agency doc show <id>                 Show a document
+agency daemon install                Install as system service
+agency daemon uninstall              Remove system service
+agency daemon start                  Start the daemon
+agency daemon stop                   Stop the daemon
+agency daemon status                 Check daemon status
+agency daemon logs                   Tail daemon logs
+agency daemon run                    Run daemon in foreground
+agency status [agent-name]           Health check
+agency config                        List all settings
+agency config <key>                  Show a setting
+agency config <key> <value>          Set a setting
+agency skills list                   List skills
+agency skills show <id>              Show a skill
+agency skills create <name>          Create a skill (stdin)
+agency skills delete <id>            Delete a skill
+agency --version                     Show version
+```
+
+## API Endpoints
+
+| Method | Route | Description |
+|--------|-------|-------------|
+| GET | `/health` | Health check |
+| GET/POST | `/agents` | List/create agents |
+| GET/PATCH/DELETE | `/agents/:name` | Agent CRUD |
+| POST | `/agents/:name/deploy` | Start an agent |
+| POST | `/agents/:name/stop` | Stop an agent |
+| GET | `/agents/:name/config/:type` | Get agent's role config |
+| GET/POST | `/tasks` | List/create tasks |
+| GET/PATCH | `/tasks/:id` | Task details/update |
+| POST | `/tasks/:id/assign` | Assign agent |
+| GET/POST | `/tasks/:id/messages` | Task comments |
+| GET | `/activities` | Activity feed |
+| GET | `/notifications/pending/:agent` | Pending notifications |
+| GET/POST | `/knowledge` | Knowledge base |
+| GET/POST | `/documents` | Documents |
+| GET/PUT/DELETE | `/settings` | Settings (key-value) |
+| GET/POST/PUT/DELETE | `/skills` | Skills (markdown docs) |
+| GET/PUT/DELETE | `/role-configs/:role/:type` | Role configuration docs |
+
+## Database Schema
+
+All state lives in `.agency/agency.db` (SQLite):
+
+- **agents** — Name, role, status, location, tokens
+- **tasks** — Title, description, design, acceptance, priority, status, parent
+- **task_assignees** — Agent-to-task assignments
+- **messages** — Task comments
+- **activities** — Event log
+- **notifications** — Delivery queue
+- **documents** — Task-linked documents
+- **knowledge** — Tagged knowledge base
+- **settings** — Key-value config (grouped by category)
+- **skills** — Markdown skill documents
+- **role_configs** — Role configuration documents (heartbeat, tools, agents, etc.)
+
+## Dashboard
+
+Five views accessible from the top nav:
+
+- **Mission Control** — Agent roster + task kanban board + live activity feed
+- **Agent Config** — Browse agent workspace files (served from role_configs in DB)
+- **Settings** — Categorized editor for Identity, AI Provider, AWS, and SSH configuration
+- **Skills** — Markdown editor for team skills
+- **Roles** — Markdown editor for role configs (Heartbeat, Tools, Agents, etc.)
+
+![Agent Config](docs/images/agent_ui_agent_config.png)
+
+### Settings
+
+Sensitive values (API keys, SSH keys, credentials) are masked in the API and revealed on demand in the UI. AI provider settings support both direct API key entry and Claude Max OAuth (import tokens from Claude Code with one click).
+
+| | |
+|---|---|
+| ![Identity](docs/images/agency_ui_identity_settings.png) | ![AI Provider](docs/images/agency_ui_ai_prodivder_settings.png) |
+| ![AWS](docs/images/agency_ui_aws_settings.png) | |
+
+## How It Works
+
+### Agents
+
+Every agent in Agency is an [OpenClaw](https://openclaw.ai/) instance. OpenClaw provides the core capabilities — shell access, file I/O, browser control, persistent memory, and multi-model support. Agency layers on top of that with:
+
+- **Role configs** — each agent gets injected with role-specific prompts (Soul, Identity, Tools, Agents, Heartbeat) that define its behavior
+- **Task coordination** — agents poll the Agency API for assigned work, post progress via task comments, and transition tasks through the workflow
+- **Fleet management** — deploy agents locally (Bun subprocess), via Docker, or on EC2 with automatic SSH tunnels
+
+Agents can run any model OpenClaw supports (Claude, GPT, local models), configured through the AI Provider settings.
+
+### Deployment Modes
+
+| Mode | How it works |
+|------|-------------|
+| **Local** | Spawns a Bun subprocess on the host machine. Agent talks to API at `localhost:3100` directly. |
+| **Docker** | Runs `docker compose up` for the agent container. |
+| **EC2** | Opens a reverse SSH tunnel from the remote instance back to the host, so the agent's `agency` CLI hits `localhost:3100` on the remote machine which tunnels back to the host API. |
+
+#### EC2 Agent Setup
+
+1. Configure SSH in Settings → SSH (paste your private key, set the username)
+2. Add `host` to the agent's entry in `.agency/fleet.json`:
+
+```json
+{
+  "agents": {
+    "nova": { "role": "implementer", "location": "ec2", "host": "54.123.45.67" }
+  }
+}
+```
+
+3. Click **Deploy** in the dashboard (or `agency start nova`)
+
+The daemon opens `ssh -R 3100:localhost:3100 user@host -N` — a persistent reverse tunnel with auto-reconnect. The remote agent's CLI commands (`agency tasks list`, `agency msg`, etc.) hit `localhost:3100` which forwards through the tunnel to the host API. No agent-side configuration needed.
+
+On stop, the tunnel is torn down. On daemon shutdown, all tunnels are cleaned up.
+
+You can also SSH directly into any EC2 agent:
+
+```bash
+agency ssh nova          # interactive shell
+agency ssh nova ls -la   # run a command
+```
+
+### Task Lifecycle
+
+```
+inbox → assigned → in_progress → review → done
+                        │
+                        ▼
+                    needs_input
+```
+
+1. Human or orchestrator creates a task
+2. Task is assigned to a worker agent
+3. Worker picks it up, does the work
+4. Worker moves to review
+5. Orchestrator/human reviews and closes
+
+### Knowledge Sharing
+
+Agents build collective knowledge through the CLI and API:
+
+```bash
+agency learn "postgres migrations need --lock-timeout 5s" --tags postgres,migrations
+agency recall "postgres migrations"
+```
+
+## Development
+
+```bash
+# From repo root
+bun install
+
+# Run everything (API + dashboard)
+bun run dev
+
+# Or run just the API
+DATABASE_PATH=.agency/agency.db bun run src/api/index.ts
+
+# Run migrations
+DATABASE_PATH=.agency/agency.db bun run src/api/db/migrate.ts
+
+# Build dashboard for production
+bun run build
+```
+
+## License
+
+MIT

package/bin/agency.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import("../src/cli/index.ts");

package/dashboard/out/404.html

@@ -0,0 +1 @@
+<!DOCTYPE html><!--pU1nwWH_dNUOCI8y4nl3C--><html lang="en"><head><meta charSet="utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="/_next/static/css/27d1ea794f04e96a.css" data-precedence="next"/><link rel="preload" as="script" fetchPriority="low" href="/_next/static/chunks/webpack-4e6bf084ac60582b.js"/><script src="/_next/static/chunks/4bd1b696-c023c6e3521b1417.js" async=""></script><script src="/_next/static/chunks/255-67e8754147461423.js" async=""></script><script src="/_next/static/chunks/main-app-1d848b791b823fa6.js" async=""></script><meta name="robots" content="noindex"/><title>404: This page could not be found.</title><title>Mission Control</title><meta name="description" content="Agency AI Dashboard"/><script src="/_next/static/chunks/polyfills-42372ed130431b0a.js" noModule=""></script></head><body class="min-h-screen"><div hidden=""><!--$--><!--/$--></div><div style="font-family:system-ui,&quot;Segoe UI&quot;,Roboto,Helvetica,Arial,sans-serif,&quot;Apple Color Emoji&quot;,&quot;Segoe UI Emoji&quot;;height:100vh;text-align:center;display:flex;flex-direction:column;align-items:center;justify-content:center"><div><style>body{color:#000;background:#fff;margin:0}.next-error-h1{border-right:1px solid rgba(0,0,0,.3)}@media (prefers-color-scheme:dark){body{color:#fff;background:#000}.next-error-h1{border-right:1px solid rgba(255,255,255,.3)}}</style><h1 class="next-error-h1" style="display:inline-block;margin:0 20px 0 0;padding:0 23px 0 0;font-size:24px;font-weight:500;vertical-align:top;line-height:49px">404</h1><div style="display:inline-block"><h2 style="font-size:14px;font-weight:400;line-height:49px;margin:0">This page could not be found.</h2></div></div></div><!--$--><!--/$--><script src="/_next/static/chunks/webpack-4e6bf084ac60582b.js" id="_R_" async=""></script><script>(self.__next_f=self.__next_f||[]).push([0])</script><script>self.__next_f.push([1,"1:\"$Sreact.fragment\"\n2:I[9766,[],\"\"]\n3:I[8924,[],\"\"]\n4:I[4431,[],\"OutletBoundary\"]\n6:I[5278,[],\"AsyncMetadataOutlet\"]\n8:I[4431,[],\"ViewportBoundary\"]\na:I[4431,[],\"MetadataBoundary\"]\nb:\"$Sreact.suspense\"\nd:I[7150,[],\"\"]\n:HL[\"/_next/static/css/27d1ea794f04e96a.css\",\"style\"]\n"])</script><script>self.__next_f.push([1,"0:{\"P\":null,\"b\":\"pU1nwWH_dNUOCI8y4nl3C\",\"p\":\"\",\"c\":[\"\",\"_not-found\"],\"i\":false,\"f\":[[[\"\",{\"children\":[\"/_not-found\",{\"children\":[\"__PAGE__\",{}]}]},\"$undefined\",\"$undefined\",true],[\"\",[\"$\",\"$1\",\"c\",{\"children\":[[[\"$\",\"link\",\"0\",{\"rel\":\"stylesheet\",\"href\":\"/_next/static/css/27d1ea794f04e96a.css\",\"precedence\":\"next\",\"crossOrigin\":\"$undefined\",\"nonce\":\"$undefined\"}]],[\"$\",\"html\",null,{\"lang\":\"en\",\"children\":[\"$\",\"body\",null,{\"className\":\"min-h-screen\",\"children\":[\"$\",\"$L2\",null,{\"parallelRouterKey\":\"children\",\"error\":\"$undefined\",\"errorStyles\":\"$undefined\",\"errorScripts\":\"$undefined\",\"template\":[\"$\",\"$L3\",null,{}],\"templateStyles\":\"$undefined\",\"templateScripts\":\"$undefined\",\"notFound\":\"$undefined\",\"forbidden\":\"$undefined\",\"unauthorized\":\"$undefined\"}]}]}]]}],{\"children\":[\"/_not-found\",[\"$\",\"$1\",\"c\",{\"children\":[null,[\"$\",\"$L2\",null,{\"parallelRouterKey\":\"children\",\"error\":\"$undefined\",\"errorStyles\":\"$undefined\",\"errorScripts\":\"$undefined\",\"template\":[\"$\",\"$L3\",null,{}],\"templateStyles\":\"$undefined\",\"templateScripts\":\"$undefined\",\"notFound\":\"$undefined\",\"forbidden\":\"$undefined\",\"unauthorized\":\"$undefined\"}]]}],{\"children\":[\"__PAGE__\",[\"$\",\"$1\",\"c\",{\"children\":[[[\"$\",\"title\",null,{\"children\":\"404: This page could not be found.\"}],[\"$\",\"div\",null,{\"style\":{\"fontFamily\":\"system-ui,\\\"Segoe UI\\\",Roboto,Helvetica,Arial,sans-serif,\\\"Apple Color Emoji\\\",\\\"Segoe UI Emoji\\\"\",\"height\":\"100vh\",\"textAlign\":\"center\",\"display\":\"flex\",\"flexDirection\":\"column\",\"alignItems\":\"center\",\"justifyContent\":\"center\"},\"children\":[\"$\",\"div\",null,{\"children\":[[\"$\",\"style\",null,{\"dangerouslySetInnerHTML\":{\"__html\":\"body{color:#000;background:#fff;margin:0}.next-error-h1{border-right:1px solid rgba(0,0,0,.3)}@media (prefers-color-scheme:dark){body{color:#fff;background:#000}.next-error-h1{border-right:1px solid rgba(255,255,255,.3)}}\"}}],[\"$\",\"h1\",null,{\"className\":\"next-error-h1\",\"style\":{\"display\":\"inline-block\",\"margin\":\"0 20px 0 0\",\"padding\":\"0 23px 0 0\",\"fontSize\":24,\"fontWeight\":500,\"verticalAlign\":\"top\",\"lineHeight\":\"49px\"},\"children\":404}],[\"$\",\"div\",null,{\"style\":{\"display\":\"inline-block\"},\"children\":[\"$\",\"h2\",null,{\"style\":{\"fontSize\":14,\"fontWeight\":400,\"lineHeight\":\"49px\",\"margin\":0},\"children\":\"This page could not be found.\"}]}]]}]}]],null,[\"$\",\"$L4\",null,{\"children\":[\"$L5\",[\"$\",\"$L6\",null,{\"promise\":\"$@7\"}]]}]]}],{},null,false]},null,false]},null,false],[\"$\",\"$1\",\"h\",{\"children\":[[\"$\",\"meta\",null,{\"name\":\"robots\",\"content\":\"noindex\"}],[[\"$\",\"$L8\",null,{\"children\":\"$L9\"}],null],[\"$\",\"$La\",null,{\"children\":[\"$\",\"div\",null,{\"hidden\":true,\"children\":[\"$\",\"$b\",null,{\"fallback\":null,\"children\":\"$Lc\"}]}]}]]}],false]],\"m\":\"$undefined\",\"G\":[\"$d\",[]],\"s\":false,\"S\":true}\n"])</script><script>self.__next_f.push([1,"9:[[\"$\",\"meta\",\"0\",{\"charSet\":\"utf-8\"}],[\"$\",\"meta\",\"1\",{\"name\":\"viewport\",\"content\":\"width=device-width, initial-scale=1\"}]]\n5:null\n"])</script><script>self.__next_f.push([1,"7:{\"metadata\":[[\"$\",\"title\",\"0\",{\"children\":\"Mission Control\"}],[\"$\",\"meta\",\"1\",{\"name\":\"description\",\"content\":\"Agency AI Dashboard\"}]],\"error\":null,\"digest\":\"$undefined\"}\n"])</script><script>self.__next_f.push([1,"c:\"$7:metadata\"\n"])</script></body></html>