agentdev-webui 1.0.0

package/public/docs.md

@@ -0,0 +1,697 @@
+# AgentDev Client
+
+Distributed agent system for automated GitHub ticket processing with Claude CLI.
+
+AgentDev is a distributed agent management platform that connects local machines running Claude CLI to a central server. Agents automatically pick up GitHub tickets tagged with `@claude`, execute the work, and stream logs back to the web dashboard in real-time.
+
+- Run automated agents on any machine with Claude CLI installed
+- Agents poll the server for available tickets and execute them autonomously
+- Real-time log streaming to the web dashboard via SSE
+- GitHub project board integration for ticket status tracking
+- Multi-project support with per-agent project assignment
+- Device flow authentication for secure agent registration
+
+## Architecture
+
+```
+┌──────────────────────────────────┐
+│  Agent Machine (your laptop/VM)  │
+│                                  │
+│  $ agentdev start                │
+│    ├── Polls for tickets (10s)   │
+│    ├── Runs Claude CLI           │
+│    └── Streams logs back         │
+│                                  │
+│  ~/agentdev-workspace/           │
+│    ├── repo-a/                   │
+│    ├── repo-b/                   │
+│    └── repo-c/                   │
+└──────────────┬───────────────────┘
+               │ HTTPS (Bearer JWT)
+               ▼
+┌──────────────────────────────────┐
+│  AgentDev Server                 │
+│  agentdev.datatamer.ai           │
+│                                  │
+│  ├── Assign tickets to agents    │
+│  ├── Store OAuth tokens (enc)    │
+│  ├── Aggregate & broadcast logs  │
+│  └── GitHub project board sync   │
+└──────────────┬───────────────────┘
+               │
+               ▼
+┌──────────────────────────────────┐
+│  GitHub                          │
+│  ├── Issues (tickets)            │
+│  ├── Project Board (statuses)    │
+│  └── Repositories (code)         │
+└──────────────────────────────────┘
+```
+
+## Installation
+
+### Prerequisites
+
+| Requirement | Version | Check |
+|-------------|---------|-------|
+| Node.js | 18+ | `node --version` |
+| Claude CLI | latest | `claude --version` |
+| Git | any | `git --version` |
+
+### Install via npm
+
+```bash
+npm install -g @datatamer/agentdev
+```
+
+### Verify Installation
+
+```bash
+agentdev --version
+# 1.0.0
+```
+
+> **Note:** The GitHub CLI (`gh`) is optional. AgentDev includes its own GitHub API integration via `agentdev gh`.
+
+## Quick Start
+
+```bash
+# 1. Register your agent with the server
+agentdev register
+
+# 2. Approve the device code in your browser
+#    Visit the URL shown and enter the code
+
+# 3. Start processing tickets
+agentdev start
+
+# 4. Check status
+agentdev status
+```
+
+That's it. Your agent will poll for tickets, execute them with Claude CLI, and stream logs to the dashboard.
+
+## Agent Registration
+
+Each agent must be registered with the server before it can claim work. Registration uses the OAuth 2.0 Device Authorization Grant flow.
+
+### Step 1: Run Register
+
+```bash
+agentdev register
+# or with options:
+agentdev register --url https://agentdev.datatamer.ai --name my-agent
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-u, --url` | `https://agentdev.datatamer.ai` | Server URL |
+| `-n, --name` | System hostname | Agent display name |
+
+### Step 2: Approve in Browser
+
+The terminal will display a user code and verification URL:
+
+```
+✓ Device code obtained
+  Code: ABCD-EFGH
+  Visit: https://agentdev.datatamer.ai/device
+  Waiting for approval...
+```
+
+1. Open the verification URL in your browser
+2. Log in to AgentDev if not already signed in
+3. Enter the user code displayed in your terminal
+4. Select the project to assign the agent to
+5. Click "Approve Agent"
+
+### Step 3: Confirmation
+
+```
+✓ Agent registered successfully!
+  Agent ID: agent-1704067200-abc123
+  Project: DataTamer (#1)
+```
+
+Your agent token and project configuration are saved to `~/.config/agentdev/config.json`.
+
+## Device Flow Authentication
+
+AgentDev uses the OAuth 2.0 Device Authorization Grant (RFC 8628) for agent authentication. This is ideal for headless servers and CLI tools that can't open a browser.
+
+### How It Works
+
+1. Agent requests a device code from the server
+2. Server returns a short user code (e.g., `ABCD-EFGH`) and verification URL
+3. User visits the URL in a browser and enters the code
+4. User approves and selects a project for the agent
+5. Agent polls the server until the code is approved (every 5 seconds)
+6. Server returns a JWT token valid for 90 days
+
+### JWT Token
+
+| Field | Description |
+|-------|-------------|
+| `agent_id` | Unique agent identifier |
+| `user_id` | ID of the user who approved the agent |
+| `project_id` | Assigned project ID |
+| `type` | Always `"agent"` |
+| `exp` | Expires in 90 days |
+
+## Configuration
+
+Configuration is stored at `~/.config/agentdev/config.json` and managed via the `agentdev config` command or set automatically during registration.
+
+### Config File
+
+```json
+{
+  "api_url": "https://agentdev.datatamer.ai",
+  "agent_token": "eyJhbGciOi...",
+  "agent_id": "agent-1704067200-abc123",
+  "agent_name": "my-laptop",
+  "max_concurrent": 1,
+  "github_org": "data-tamer",
+  "project_id": "PVT_kwDOCJIWbs4AnuSZ",
+  "project_number": 1,
+  "status_field_id": "PVTSSF_lADOCJIWbs4AnuSZzgfaWGs",
+  "status_options": {
+    "TODO": "f75ad846",
+    "IN_PROGRESS": "47fc9ee4",
+    "TEST": "c48bc058",
+    "DONE": "98236657"
+  }
+}
+```
+
+### Managing Config
+
+```bash
+# View all settings
+agentdev config get
+
+# View a specific key
+agentdev config get api_url
+
+# Update a setting
+agentdev config set api_url https://agentdev.datatamer.ai
+```
+
+## CLI Commands
+
+### agentdev register
+
+Register this agent with the AgentDev server using device flow authentication.
+
+```bash
+agentdev register [--url <url>] [--name <name>]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-u, --url` | `https://agentdev.datatamer.ai` | Server URL |
+| `-n, --name` | hostname | Agent name |
+
+### agentdev start
+
+Start the agent in daemon mode. Continuously polls for work and executes tickets.
+
+```bash
+agentdev start [--concurrent <number>]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-c, --concurrent` | `1` | Max concurrent tickets |
+
+Behavior:
+
+- Polls for work every **10 seconds**
+- Sends heartbeat every **30 seconds**
+- Syncs Claude skills to `~/.claude/commands/`
+- Fetches GitHub OAuth tokens from server
+- 30-second backoff on errors
+- Graceful shutdown on SIGINT/SIGTERM
+
+### agentdev cron
+
+Run in batch/cron mode. Processes all available tickets in cycles with a configurable interval.
+
+```bash
+agentdev cron [--interval <minutes>] [--max-tickets <number>]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-i, --interval` | `5` | Minutes between cycles |
+| `-m, --max-tickets` | `10` | Max tickets per cycle |
+
+Ideal for CI/CD pipelines or scheduled batch processing.
+
+### agentdev status
+
+Display the agent's registration status and configuration.
+
+```bash
+agentdev status
+```
+
+Shows: agent ID, name, API URL, registration status, config file location.
+
+### agentdev config
+
+View and modify configuration values.
+
+```bash
+# View all config
+agentdev config get
+
+# View single key
+agentdev config get api_url
+
+# Set a value
+agentdev config set max_concurrent 2
+```
+
+### agentdev ticket
+
+Create and manage tickets from the command line.
+
+```bash
+# Create a ticket
+agentdev ticket create -R my-repo \
+  --title "Fix login bug" \
+  --body "The login form crashes on submit" \
+  --claude
+
+# Output (JSON)
+agentdev ticket create -R my-repo --title "..." --json
+```
+
+| Option | Description |
+|--------|-------------|
+| `-R <repo>` | Repository name (under the org) |
+| `--title` | Issue title |
+| `--body` | Issue body text |
+| `--body-file` | Read body from file |
+| `--claude / --no-claude` | Append `@claude` tag (default: true) |
+| `--json` | Output as JSON |
+
+Creates the GitHub issue, adds it to the project board, and sets status to "Todo".
+
+### agentdev gh
+
+GitHub CLI replacement with pre-configured authentication. Uses the agent's OAuth token.
+
+#### Issues
+
+```bash
+# View an issue
+agentdev gh issue view 42 -R owner/repo
+
+# Create an issue
+agentdev gh issue create -R owner/repo --title "Bug" --body "Details"
+
+# Comment on an issue
+agentdev gh issue comment 42 -R owner/repo --body "Fixed in PR #43"
+
+# Reopen an issue
+agentdev gh issue reopen 42 -R owner/repo
+```
+
+#### Pull Requests
+
+```bash
+# Create a PR
+agentdev gh pr create -R owner/repo \
+  --title "Fix bug" --body "Description" \
+  --head feature-branch --base main
+
+# View a PR
+agentdev gh pr view 43 -R owner/repo --json state,title
+
+# Merge a PR
+agentdev gh pr merge 43 -R owner/repo --squash
+```
+
+#### Project Board
+
+```bash
+# Update project item status
+agentdev gh project item-edit \
+  --id ITEM_ID \
+  --project-id PROJECT_ID \
+  --field-id FIELD_ID \
+  --single-select-option-id OPTION_ID
+```
+
+#### Raw API
+
+```bash
+# GraphQL
+agentdev gh api graphql -f query='{ viewer { login } }'
+
+# REST
+agentdev gh api rest /repos/owner/repo/issues -X GET
+```
+
+### agentdev openspec
+
+Spec-driven development commands. Wraps the `@fission-ai/openspec` CLI.
+
+```bash
+# Initialize openspec in a repo
+agentdev openspec init
+
+# List artifacts
+agentdev openspec list --specs --sort recent
+
+# Show artifact details
+agentdev openspec show my-feature --json
+
+# Validate artifacts
+agentdev openspec validate --all --strict
+
+# Get implementation instructions
+agentdev openspec instructions my-artifact --change feature-x
+
+# Archive a completed change
+agentdev openspec archive my-change --yes
+```
+
+### agentdev onboard
+
+Interactive repository discovery and environment skill generation.
+
+```bash
+agentdev onboard [--workspace <path>] [--no-claude] [--force]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-w, --workspace` | current dir | Workspace root to scan |
+| `--no-claude` | false | Use templates instead of Claude generation |
+| `--force` | false | Overwrite existing skills |
+
+The onboard command:
+
+1. Scans the workspace for git repositories
+2. Detects language, framework, databases, test runner, Docker setup
+3. Prompts you to select repos to onboard
+4. Asks for environment details (deploy method, test commands, DB connections)
+5. Generates Claude skill files at `.claude/commands/env-<name>.md`
+6. Saves structured metadata to `.claude/repo-spec.json`
+
+#### Detected Technologies
+
+| Category | Detected |
+|----------|----------|
+| Languages | JavaScript, TypeScript, Python |
+| Frameworks | Next.js, Express, Fastify, FastAPI, Django, Flask |
+| Databases | PostgreSQL, MySQL, MongoDB, Redis, SQLite |
+| ORMs | Prisma, SQLAlchemy, Mongoose |
+| Test Runners | Jest, Vitest, Mocha, pytest, Playwright |
+| Package Managers | npm, yarn, pnpm, pip, poetry, uv |
+
+## How Agents Work
+
+```
+Agent starts: agentdev start
+        │
+        ├── Sync Claude skills to ~/.claude/commands/
+        ├── Fetch OAuth tokens (GitHub) from server
+        ├── Start heartbeat (every 30s)
+        │
+        ▼
+┌─── Poll Loop (every 10s) ──────────────────────────┐
+│                                                      │
+│  GET /api/agent/work                                 │
+│    ├── No ticket → print "." → wait 10s → loop      │
+│    └── Ticket found ↓                                │
+│                                                      │
+│  Execute Ticket                                      │
+│    ├── Set GH_TOKEN in env                           │
+│    ├── Spawn: claude -p --dangerously-skip-perms     │
+│    │         /auto-ticket-workflow                    │
+│    ├── Stream logs → POST /api/agent/logs (2s batch) │
+│    ├── Check stop signal (every 5s)                  │
+│    └── On exit → POST /api/agent/complete            │
+│                                                      │
+│  Loop back ↑                                         │
+└──────────────────────────────────────────────────────┘
+```
+
+### Heartbeat
+
+Every **30 seconds**, the agent sends a heartbeat to keep its status updated on the server.
+
+```
+POST /api/agent/heartbeat
+Authorization: Bearer <token>
+
+{
+  "status": "idle",        // or "busy"
+  "current_ticket": null   // or ticket ID
+}
+```
+
+If the server doesn't receive a heartbeat for an extended period, the agent is considered offline.
+
+### Ticket Execution
+
+When an agent claims a ticket, it:
+
+1. Sets `GH_TOKEN` environment variable from the server's OAuth tokens
+2. Creates a temp file for Claude output (avoids pipe buffering)
+3. Spawns Claude CLI:
+   ```bash
+   claude -p --dangerously-skip-permissions \
+     --output-format stream-json --verbose
+   ```
+4. Sends the `/auto-ticket-workflow` skill as the prompt
+5. Tails the output file and parses stream-json in real-time
+6. Batches parsed logs to the server every 2 seconds
+7. Polls `/api/agent/should-stop` every 5 seconds (kills process if requested)
+8. On process exit, reports completion via `/api/agent/complete`
+
+### Log Streaming
+
+Logs are batched and uploaded to the server in real-time:
+
+- **Batch interval:** every 2 seconds
+- **Batch size:** up to 10 log entries
+- **Parsed content:** text output, tool calls, tool results, cost info
+
+The server stores logs in PostgreSQL and broadcasts them to the web dashboard via SSE (Server-Sent Events).
+
+## API Reference
+
+### Device Flow Endpoints
+
+#### POST /api/agent/device/code
+
+Request a new device code for agent registration.
+
+```json
+// Request
+{
+  "agent_name": "my-agent",
+  "capabilities": {
+    "cpu_cores": 8,
+    "memory_gb": 16,
+    "platform": "linux",
+    "arch": "x64",
+    "tools": ["git", "node", "claude"]
+  }
+}
+
+// Response (200)
+{
+  "device_code": "a1b2c3d4...",
+  "user_code": "ABCD-EFGH",
+  "verification_uri": "https://agentdev.datatamer.ai/device",
+  "expires_in": 600,
+  "interval": 5
+}
+```
+
+#### POST /api/agent/device/token
+
+Poll for token after user approves the device code.
+
+```json
+// Request
+{ "device_code": "a1b2c3d4..." }
+
+// Response (200 - approved)
+{
+  "access_token": "eyJhbGciOi...",
+  "token_type": "Bearer",
+  "expires_in": 7776000,
+  "agent_id": "agent-1704067200-abc123",
+  "project_id": 1
+}
+
+// Response (428 - still pending)
+{ "error": "authorization_pending" }
+```
+
+### Agent API Endpoints
+
+All endpoints require `Authorization: Bearer <token>`.
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/agent/heartbeat` | Send agent heartbeat with status |
+| GET | `/api/agent/work` | Claim the next available ticket |
+| GET | `/api/agent/oauth` | Get GitHub OAuth token |
+| POST | `/api/agent/logs` | Upload log entries |
+| POST | `/api/agent/complete` | Mark ticket as complete/failed |
+| GET | `/api/agent/should-stop` | Check for stop signal |
+| GET | `/api/agent/project-config` | Get project board configuration |
+
+#### GET /api/agent/work
+
+Claims the next available ticket for the agent's assigned project.
+
+```json
+// Response (ticket available)
+{
+  "ticket": {
+    "id": "ticket-uuid",
+    "github_issue_number": 42,
+    "github_repo": "agentdev-webui",
+    "title": "Implement dark mode",
+    "description": "Add dark theme support"
+  }
+}
+
+// Response (no tickets)
+{ "ticket": null }
+```
+
+#### POST /api/agent/logs
+
+Upload log entries. Batched by the client.
+
+```json
+// Request
+{
+  "logs": ["Log line 1", "Log line 2"],
+  "ticket_id": "ticket-uuid"
+}
+
+// Response
+{ "success": true, "count": 2 }
+```
+
+#### POST /api/agent/complete
+
+Report ticket completion or failure.
+
+```json
+// Request
+{
+  "ticket_id": "ticket-uuid",
+  "success": true,
+  "error_message": null
+}
+
+// Response
+{ "success": true }
+```
+
+#### GET /api/agent/should-stop?ticket_id=ID
+
+Check if the user has requested to stop this ticket's execution.
+
+```json
+// Response
+{ "should_stop": false }
+```
+
+### GitHub Integration
+
+The client includes a built-in GitHub API module (`agentdev gh`) that supports:
+
+- **REST API** — Issues, PRs, file uploads, generic REST calls
+- **GraphQL API** — Project board operations, custom queries
+- **Token resolution** — CLI arg → `GH_TOKEN` env → server OAuth
+
+This eliminates the dependency on the `gh` CLI while providing full GitHub API access.
+
+## Workspace Setup
+
+### Default Workspace
+
+When you run `agentdev start`, the agent uses `~/agentdev-workspace/` by default.
+
+### Custom Workspace
+
+```bash
+# Set for current session
+export AGENTDEV_WORKSPACE=/path/to/your/repos
+agentdev start
+
+# Set permanently
+echo 'export AGENTDEV_WORKSPACE=/path/to/repos' >> ~/.bashrc
+```
+
+> **Tip:** Using a custom workspace lets agents work with your existing cloned repos, avoiding redundant clones.
+
+## Claude Skills
+
+On startup, the agent syncs skill files from the package to `~/.claude/commands/`:
+
+| Skill File | Purpose |
+|------------|---------|
+| `agentdev-gh.md` | GitHub CLI command reference for Claude |
+| `agentdev-openspec.md` | OpenSpec workflow reference for Claude |
+| `auto-ticket.md` | Full ticket workflow (proposal → implement → test → deploy) |
+
+These skills are used as prompts when Claude executes tickets.
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `GH_TOKEN` | GitHub personal access token | From server OAuth |
+| `AGENTDEV_WORKSPACE` | Workspace directory path | `~/agentdev-workspace` |
+| `CLAUDE_BIN` | Path to Claude CLI binary | `claude` |
+| `TICKET_NUMBER` | Current ticket (set by executor) | — |
+| `REPO` | Current repository (set by executor) | — |
+| `AGENT_ID` | Agent identifier (set by executor) | — |
+
+## Troubleshooting
+
+### Agent not picking up tickets
+
+- Verify the agent is running: `agentdev status`
+- Check that tickets exist on the project board with status "Todo"
+- Ensure tickets have `@claude` in the description
+- Verify GitHub OAuth is configured in your Profile
+- Check that the agent is assigned to the correct project
+
+### Registration fails
+
+- Ensure the server URL is reachable: `curl https://agentdev.datatamer.ai`
+- The device code expires after 10 minutes — re-run `agentdev register`
+- Make sure you're logged into the web dashboard when approving
+
+### "claude: command not found"
+
+Install Claude CLI from [claude.ai/download](https://claude.ai/download) and ensure it's in your PATH.
+
+### Token expired
+
+Agent tokens expire after 90 days. Re-register:
+
+```bash
+agentdev register
+```
+
+### Check config file
+
+```bash
+cat ~/.config/agentdev/config.json
+```

package/public/favicon.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
+  <rect width="32" height="32" rx="6" fill="#1a1a2e"/>
+  <path d="M16 6 L26 24 H6 Z" fill="none" stroke="#4ade80" stroke-width="2.5" stroke-linejoin="round"/>
+  <circle cx="16" cy="17" r="3" fill="#4ade80"/>
+</svg>