@armanage/clarmanage 0.1.1 → 0.1.2

package/README.md

@@ -1,173 +1,45 @@
-# Clarmanage — Local AI Agent Runner
+# Clarmanage
 
-Clarmanage is a lightweight TypeScript CLI that runs on your machine and acts as a bridge between the [Armanage](../README.md) server and AI SDKs. It continuously polls the server for queued tasks, routes each task to the appropriate AI agent (Codex, Claude, Copilot, etc.), streams execution logs back in real time, and reports final results — all without exposing your local environment to the internet.
+Clarmanage is the local runner for Armanage. It connects a machine you control to your Armanage workspace so assigned AI agents can pick up tasks, work inside your environment, and send progress back to the dashboard.
 
-> Implements the architecture described in [`client_prd.md`](./client_prd.md).
+Tasks live in Armanage. Execution happens on your machine. The dashboard gets progress, not your codebase.
 
-## What is implemented
+## User Flow
 
-- Generic `Agent` interface.
-- `AgentRegistry` for modular agent registration.
-- `ClientCore` loop: authenticate -> poll -> execute -> stream logs -> mark completed/failed.
-- `CodexAgent` implementation (Phase 1 target) using real `@openai/codex-sdk`.
-- HTTP integration with Rails-style endpoints from the PRD.
-- Built-in MCP stdio server for `/api/v1/client/*`, exposed via `clarmanage mcp` and auto-attached to Codex runs.
-- Exponential backoff when no tasks are available.
-- Parallel task processing across configured agents.
-
-## Install from npm
-
-Install globally to get the `clarmanage` executable on your `PATH`:
+1. Create an agent in Armanage and copy its token.
+2. Install the runner:
 
 ```bash
 npm install -g @armanage/clarmanage
 ```
 
-Or run it without a global install:
-
-```bash
-npx @armanage/clarmanage
-```
-
-Agent tokens are stored in `~/.clarmanage/agents.json`.
-
-If `SERVER_BASE_URL` is omitted, the client falls back to `https://armanage.com`. Other runtime env vars also have built-in defaults, so you only need to override what you actually use.
-
-## Local development
-
-1. Install dependencies:
-
-```bash
-npm install
-```
-
-2. Configure environment variables (or put them in `.env`):
-
-```bash
-export SERVER_BASE_URL="http://localhost:3000"
-export CODEX_API_KEY="your-codex-or-openai-api-key"
-export CODEX_YOLO_MODE="true"
-# Optional when CODEX_YOLO_MODE=false:
-# export CODEX_SANDBOX_MODE="workspace-write"
-# export CODEX_APPROVAL_POLICY="on-request"
-export CODEX_SKIP_GIT_REPO_CHECK="true"
-export USE_MOCK_CODEX_EXECUTOR="false"
-export POLL_INTERVAL_MS="2000"
-export MAX_BACKOFF_MS="30000"
-export REQUEST_TIMEOUT_MS="15000"
-```
-
-If you skip these variables entirely, the client uses defaults such as `SERVER_BASE_URL=https://armanage.com`, `CODEX_YOLO_MODE=true`, `GEMINI_MODEL=gemini-2.5-flash`, `POLL_INTERVAL_MS=2000`, `MAX_BACKOFF_MS=30000`, and `REQUEST_TIMEOUT_MS=15000`.
-
-3. Add one or more agents:
-
-```bash
-npm run dev -- agent add
-```
-
-4. Run in development mode:
-
-```bash
-npm run dev
-```
-
-5. Or build and run:
-
-```bash
-npm run build
-npm start
-```
-
-## Run as MCP server
-
-When you run `clarmanage`, Codex sessions automatically get a built-in `clarmanage` MCP server using the same agent token that the client already uses for API calls.
-
-For manual testing or standalone MCP registration, Clarmanage can also expose the authenticated client API over MCP stdio:
-
-```bash
-export SERVER_BASE_URL="http://localhost:3000"
-npm run mcp -- your-agent-token
-```
-
-Or with the built CLI:
-
-```bash
-clarmanage mcp --token your-agent-token
-```
-
-This server exposes tools for:
-
-- `get_agent_profile`
-- `send_agent_heartbeat`
-- `list_projects`
-- `list_tasks`
-- `get_task_board`
-- `move_task`
-
-Example Codex registration:
-
-```bash
-codex mcp add clarmanage \
-  --env SERVER_BASE_URL=http://localhost:3000 \
-  -- clarmanage mcp your-agent-token
-```
-
-## Run with Mock Server
-
-1. Start mock server in terminal 1:
+3. If you use a self-hosted Armanage instance, point the runner to it:
 
 ```bash
-npm run dev:server
+export SERVER_BASE_URL="https://your-armanage.example.com"
 ```
 
-2. Set client env in terminal 2:
+4. Connect the runner to your agent:
 
 ```bash
-export SERVER_BASE_URL="http://localhost:3000"
-export CODEX_API_KEY="your-codex-or-openai-api-key"
-export USE_MOCK_CODEX_EXECUTOR="false"
+clarmanage agent add YOUR_AGENT_TOKEN
 ```
 
-If `MOCK_SERVER_PORT` is set to a different value in `.env`, use that same port in `SERVER_BASE_URL`.
-
-3. Add mock token as an agent:
+5. Start the runner:
 
 ```bash
-npm run dev -- agent add
+clarmanage
 ```
 
-4. Run client:
-
-```bash
-npm run dev
-```
+6. Create or assign tasks in Armanage. The runner picks them up, works locally, and keeps the dashboard updated with status and progress.
+7. Review the result in Armanage and stop the runner with `Ctrl+C` when you're done.
 
-5. Inspect mock state:
+## Useful Commands
 
 ```bash
-curl http://localhost:3000/api/v1/debug/state
+clarmanage
+clarmanage agent list
+clarmanage agent remove
 ```
 
-## Expected task payload for CodexAgent
-
-`CodexAgent` expects this minimal payload shape:
-
-```json
-{
-  "prompt": "Write a concise summary of this ticket",
-  "context": "Optional extra context"
-}
-```
-
-## Notes
-
-- `RealCodexExecutor` (in `src/codexExecutor.ts`) streams Codex SDK events and reports them as task logs.
-- By default the client runs Codex in YOLO mode (`CODEX_YOLO_MODE=true`), which maps to `sandbox=danger-full-access` and `approval_policy=never`.
-- Set `CODEX_YOLO_MODE=false` to use explicit `CODEX_SANDBOX_MODE` / `CODEX_APPROVAL_POLICY` values.
-- Runtime emits compact task info logs to `stdout` (including reasoning/todo summaries from streamed Codex events).
-- Set `USE_MOCK_CODEX_EXECUTOR=true` if you want a fully local run without calling the real Codex API.
-- `src/mockServer.ts` seeds one simple codex agent and one queued codex task in memory.
-- `.env` and `.env.local` are auto-loaded by both client and mock server entrypoints.
-- Agent tokens are stored in `~/.clarmanage/agents.json`.
-- CLI commands: `clarmanage`, `clarmanage agent add`, `clarmanage agent remove`, `clarmanage agent list`, `clarmanage mcp`.
-- Task completion now prefers moving to the next board column after development (for example `review`/`qa`) instead of jumping directly to `done`; if agent output includes `NEXT_STATUS`, that value is used.
+Repeat `clarmanage agent add` if you want the same machine to serve more than one agent profile.

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@armanage/clarmanage",
-  "version": "0.1.1",
-  "description": "Local AI agent runner for Armanage",
+  "version": "0.1.2",
+  "description": "Local runner for Armanage AI agents",
   "type": "module",
   "bin": {
-    "clarmanage": "./dist/clarmanage.js"
+    "clarmanage": "dist/clarmanage.js"
   },
   "files": [
     "dist",