{"id":47595733,"url":"https://github.com/vtstech/acp-agent-control-panel","last_synced_at":"2026-04-01T18:04:09.471Z","repository":{"id":344040493,"uuid":"1180195950","full_name":"VTSTech/ACP-Agent-Control-Panel","owner":"VTSTech","description":"A lightweight monitoring and observability sidecar for AI agents. Provides real-time tracking of agent activities, token usage, shell commands, and task management through a web UI and REST API.","archived":false,"fork":false,"pushed_at":"2026-03-30T21:38:59.000Z","size":401,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-30T22:13:21.678Z","etag":null,"topics":["acp","agents","ai","workflows"],"latest_commit_sha":null,"homepage":"https://www.vts-tech.org/","language":"Python","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/VTSTech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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-03-12T19:54:35.000Z","updated_at":"2026-03-30T21:39:04.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/VTSTech/ACP-Agent-Control-Panel","commit_stats":null,"previous_names":["vtstech/acp-agent-control-panel"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/VTSTech/ACP-Agent-Control-Panel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VTSTech%2FACP-Agent-Control-Panel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VTSTech%2FACP-Agent-Control-Panel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VTSTech%2FACP-Agent-Control-Panel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VTSTech%2FACP-Agent-Control-Panel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/VTSTech","download_url":"https://codeload.github.com/VTSTech/ACP-Agent-Control-Panel/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VTSTech%2FACP-Agent-Control-Panel/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31290742,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","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":["acp","agents","ai","workflows"],"created_at":"2026-04-01T18:03:59.604Z","updated_at":"2026-04-01T18:04:09.448Z","avatar_url":"https://github.com/VTSTech.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ACP - Agent Control Panel\n\nA lightweight monitoring and observability sidecar for AI agents. Provides real-time tracking of agent activities, token usage, shell commands, and task management through a web UI and REST API.\n\n[![made-with-Markdown](https://img.shields.io/badge/Made%20with-Markdown-1f425f.svg)](http://commonmark.org)\n\n\u003cimg width=\"1803\" height=\"910\" alt=\"image\" src=\"https://github.com/user-attachments/assets/d3642535-e903-4996-beaf-60fbea802171\" /\u003e\n\n## Quick Start\n\n```bash\n# Minimal version (single file, ~400 lines)\npython acp-minimal.py\n\n# Full version (production ready)\npython VTSTech-GLMACP.py\n\n# Open http://localhost:8766 (default: admin/secret)\n```\n\n## What ACP Does\n\nACP acts as a \"dashboard\" for AI agents, allowing them to:\n\n- **Report Activities** - Log what they're doing (reading files, running commands, etc.)\n- **Track Token Usage** - Monitor context window consumption\n- **Shell History** - Record terminal commands executed\n- **Task Management** - Sync TODO lists and track progress\n- **Stop/Resume** - Allow humans to pause agent activity\n- **Context Recovery** - Preserve session state across context compressions\n\n## Versions\n\n### Minimal (`acp-minimal.py`) - Reference Implementation\n- **~400 lines** of pure Python (no dependencies)\n- Single file, drop-in solution\n- Basic web UI included\n- Core API endpoints only\n- Perfect for learning the protocol or simple integrations\n\n### Full Version (`VTSTech-GLMACP.py`) - Production Ready\nThe full implementation includes everything in minimal plus:\n\n| Feature | Description |\n|---------|-------------|\n| **File Browser** | View and browse files the agent has accessed |\n| **Syntax Highlighting** | Code highlighting for 50+ languages |\n| **Line Numbers** | Optional line numbers in file viewer |\n| **Activity Filters** | Filter by action type, status, date range |\n| **Search** | Full-text search across activities |\n| **Changelog UI** | Version history and release notes |\n| **Optional CSRF** | Security hardening (disabled by default) |\n| **Rate Limiting** | Prevent API abuse |\n| **Better Token Estimation** | Improved token counting heuristics |\n| **Configurable Context Window** | Environment variable `GLMACP_CONTEXT_WINDOW` |\n| **File Token Deduplication** | Don't double-count re-read files |\n| **Seamless Restarts** | SO_REUSEPORT for zero-downtime reload |\n| **v1.0.1** Activity Priority | `high` \\| `medium` \\| `low` priority field |\n| **v1.0.1** Activity Metadata | Arbitrary key-value pairs with `agent_name` support |\n| **v1.0.1** Content Size | Accurate token tracking for native tools |\n| **v1.0.1** Activity Lookup | GET /api/activity/{id} endpoint |\n| **v1.0.1** Activity Hints | Contextual hints in /api/action response |\n| **v1.0.1** CHAT Action Type | Track conversational/cognitive work |\n| **v1.0.1** whoami Endpoint | GET /api/whoami for agent self-awareness |\n| **v1.0.2** Nudge API | Human guidance via synchronous message delivery |\n| **v1.0.2** Orphan Detection | Warning when starting tasks with running activities |\n| **v1.0.2** Nudge Priority | `normal` \\| `high` \\| `urgent` priority levels |\n| **v1.0.2** TODO/Shell Metadata | `agent_name`, `tool`, `skill` attribution |\n| **v1.0.3** Per-Agent Tokens | `primary_agent`, `agent_tokens{}` for context isolation |\n| **v1.0.3** Context Isolation | Session tokens reflect only primary agent context |\n| **v1.0.3** File Deduplication | READ skips tokens for already-read files |\n| **v1.0.3** Duration Statistics | GET /api/stats/duration for performance analysis |\n| **v1.0.3** Batch Operations | POST /api/activity/batch for bulk activities |\n| **v1.0.3** Cloudflared Tunnel | Built-in tunnel support via `GLMACP_TUNNEL=auto` |\n| **v1.0.4** Agent Registry | Register agents, track online status, capabilities |\n| **v1.0.4** A2A Messaging | Inter-agent communication via message queue |\n| **v1.0.4** A2A Hints | Notification of pending messages in activity response |\n| **v1.0.4** JSON-RPC 2.0 | A2A protocol compliance via `/jsonrpc`, `/a2a` endpoints |\n| **v1.0.4** Agent Card | `/.well-known/agent-card.json` for A2A discovery |\n| **v1.0.5** Primary Agent in whoami | `primary_agent` field in `/api/whoami` response |\n| **v1.0.5** Nudge Delivery | Nudges delivered only to primary agent |\n| **v1.0.5** Context Isolation | Secondary agents receive `nudge: null` |\n| **v1.0.6** TODO Toggle | `POST /api/todos/toggle` endpoint |\n| **v1.0.6** Nudge Polling | `GET /api/nudge` check pending without logging |\n| **v1.0.6** CORS Support | CORS headers and OPTIONS preflight handling |\n\n\n## API Reference\n\n### Core Endpoints\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | `/api/status` | Get current state (running, history, tokens, stop_flag) |\n| GET | `/api/all` | Combined status + running + history in one call |\n| POST | `/api/action` | Combined log/complete workflow (recommended) |\n| POST | `/api/start` | Start a new activity |\n| POST | `/api/complete` | Complete an activity |\n| POST | `/api/stop` | Set stop flag, cancel running activities |\n| POST | `/api/resume` | Clear stop flag |\n| POST | `/api/shutdown` | **v1.0.2** Gracefully end session with summary export |\n| GET | `/api/running` | List currently running activities |\n| GET | `/api/history` | Get activity history |\n| GET | `/api/activity/{id}` | **v1.0.1** Get single activity by ID |\n| GET | `/api/whoami` | **v1.0.1** Agent self-awareness and identity hint |\n| GET | `/api/csrf-token` | Get CSRF token (if enabled) |\n| POST | `/api/clear_history` | Clear activity history |\n| POST | `/api/reset_session` | Reset session tokens to startup value |\n| POST | `/api/reset` | **v1.0.4** Full session reset including agents and A2A messages |\n| POST | `/api/nudge` | **v1.0.2** Send guidance to agent |\n| GET | `/api/nudge` | **v1.0.2** Check pending nudge |\n| POST | `/api/nudge/ack` | **v1.0.2** Acknowledge nudge |\n| GET | `/api/stats/duration` | **v1.0.3** Activity duration statistics |\n| POST | `/api/activity/batch` | **v1.0.3** Batch activity operations |\n| GET | `/api/agents` | **v1.0.4** List all registered agents |\n| GET | `/api/agents/{name}` | **v1.0.4** Get specific agent details |\n| POST | `/api/agents/register` | **v1.0.4** Register agent with capabilities |\n| POST | `/api/agents/unregister` | **v1.0.4** Unregister an agent |\n| POST | `/api/a2a/send` | **v1.0.4** Send message to another agent |\n| GET | `/api/a2a/history` | **v1.0.4** Get A2A message history |\n| GET | `/.well-known/agent-card.json` | **v1.0.4** A2A Agent Card discovery |\n| POST | `/jsonrpc` `/a2a` `/api/jsonrpc` | **v1.0.4** JSON-RPC 2.0 endpoint |\n\n### Extended Endpoints (Full Version)\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | `/api/files/list` | List directory contents |\n| GET | `/api/files/view` | View file content with token count |\n| GET | `/api/files/download` | Download file (binary safe) |\n| POST | `/api/files/upload` | Upload file |\n| POST | `/api/files/save` | Save edited file |\n| POST | `/api/files/delete` | Delete file or directory |\n| POST | `/api/files/mkdir` | Create directory |\n| POST | `/api/files/extract` | Extract archive |\n| POST | `/api/files/compress` | Create zip archive |\n| GET | `/api/system` | CPU, RAM, disk statistics |\n| GET | `/api/session` | Session info and timeout |\n| POST | `/api/session/refresh` | Extend session timeout |\n| POST | `/api/restart` | Restart the ACP server |\n| GET | `/api/summary` | Get session summary for context recovery |\n| GET | `/api/summary/export` | Export summary to persistent markdown file |\n| GET | `/api/notes` | Get all saved notes |\n| POST | `/api/notes/add` | Add note for context recovery |\n| POST | `/api/notes/clear` | Clear all AI notes |\n| GET | `/api/todos` | Get current TODO list |\n| POST | `/api/todos/update` | Replace entire TODO list |\n| POST | `/api/todos/add` | Add single TODO item |\n| POST | `/api/todos/clear` | Clear completed TODOs |\n| GET | `/api/shell` | Get shell command history |\n| POST | `/api/shell/add` | Add shell command to history |\n| POST | `/api/shell/clear` | Clear shell history |\n\n### Action Parameters (v1.0.1)\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `action` | string | Action type (required) |\n| `target` | string | File path, command, or resource (required) |\n| `details` | string | Human-readable description |\n| `content_size` | integer | Character count for accurate token tracking |\n| `priority` | string | `high` \\| `medium` \\| `low` (default: medium) |\n| `metadata` | object | Arbitrary key-value pairs (e.g., `{\"agent_name\": \"Super Z\"}`) |\n\n### Action Types\n\n| Action | Target Example | Details |\n|--------|----------------|---------|\n| `READ` | `/path/to/file.py` | File being read |\n| `WRITE` | `/path/to/output.md` | File being written |\n| `EDIT` | `/path/to/file.py` | File being modified |\n| `BASH` | `npm install` | Shell command |\n| `SEARCH` | `pattern` | Search operation |\n| `SKILL` | `image-generation` | Skill invocation |\n| `API` | `POST https://api.example.com` | External API call |\n| `TODO` | `task-id-123` | TODO update |\n| `CHAT` | `discussion topic` | **v1.0.1** Conversational/cognitive work |\n| `A2A` | `AgentA → AgentB` | **v1.0.4** Agent-to-agent communication |\n\n## Integration Pattern\n\nAgents should follow this workflow:\n\n```\n0. SESSION START (mandatory)\n   GET /api/whoami              → Establish identity (use agent_name in metadata)\n   POST /api/agents/register   → Register with Agent Registry (v1.0.4)\n   GET /api/todos               → Restore TODO state\n   POST /api/action             → Log bootstrap activity (CHAT, \"Session bootstrap\")\n\n1. CHECK STATUS → GET /api/status (check stop_flag)\n2. LOG ACTION   → POST /api/action (with action, target, details, metadata)\n3. EXECUTE      → Do the actual work\n4. COMPLETE     → POST /api/action (with complete_id, result)\n```\n\n### Example: Reading a File\n\n```python\nimport requests\n\nACP_URL = \"http://localhost:8766\"\nAUTH = (\"admin\", \"secret\")\n\n# 0. Session start - establish identity\nwhoami = requests.get(f\"{ACP_URL}/api/whoami\", auth=AUTH).json()\nagent_name = \"MyAgent\"  # Use this in all activity metadata\n\n# Register with agent registry (v1.0.4)\nrequests.post(f\"{ACP_URL}/api/agents/register\", auth=AUTH, json={\n    \"agent_name\": agent_name,\n    \"capabilities\": [\"file-reading\", \"code-analysis\"]\n})\n\n# 1. Check if we should stop\nstatus = requests.get(f\"{ACP_URL}/api/status\", auth=AUTH).json()\nif status[\"stop_flag\"]:\n    print(f\"Stop requested: {status['stop_reason']}\")\n    exit(1)\n\n# 2. Log action start (include content_size, priority, metadata)\nresp = requests.post(f\"{ACP_URL}/api/action\", auth=AUTH, json={\n    \"action\": \"READ\",\n    \"target\": \"/home/user/project/main.py\",\n    \"details\": \"Reading source file\",\n    \"priority\": \"high\",\n    \"metadata\": {\"agent_name\": agent_name, \"source\": \"user_request\"}\n})\nactivity_id = resp.json()[\"activity_id\"]\n\n# Check A2A hints for pending messages (v1.0.4)\nhints = resp.json().get(\"hints\", {})\nif hints.get(\"a2a\", {}).get(\"pending_count\", 0) \u003e 0:\n    messages = requests.get(f\"{ACP_URL}/api/a2a/history?to={agent_name}\", auth=AUTH).json()\n    # process messages...\n\n# 3. Execute\ncontent = open(\"/home/user/project/main.py\").read()\n\n# 4. Complete (include content_size for accurate token tracking)\nrequests.post(f\"{ACP_URL}/api/action\", auth=AUTH, json={\n    \"complete_id\": activity_id,\n    \"result\": f\"Read {len(content)} bytes\",\n    \"complete_content_size\": len(content),\n    \"complete_metadata\": {\"lines\": content.count(chr(10))}\n})\n```\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `GLMACP_PORT` | `8766` | Server port |\n| `GLMACP_USER` | `admin` | HTTP Basic Auth username |\n| `GLMACP_PASS` | `secret` | HTTP Basic Auth password |\n| `GLMACP_DATA_FILE` | `./agent_activity.json` | Session state storage file path |\n| `GLMACP_FILES_DIR` | *(script parent)* | Base directory for file manager |\n| `GLMACP_SUMMARY_FILE` | `./acp_session_summary.md` | Context recovery summary file path |\n| `GLMACP_QUIET` | `false` | Suppress server log output |\n| `GLMACP_CSRF_ENABLED` | `false` | Enable CSRF protection (recommended for production) |\n| `GLMACP_CONTEXT_WINDOW` | `200000` | Token limit for progress bar |\n| `GLMACP_STARTUP_TOKENS` | `3000` | Initial token overhead estimate |\n| `GLMACP_SESSION_TIMEOUT` | `86400` | Session timeout in seconds |\n| `GLMACP_MAX_UPLOAD_SIZE` | `104857600` | Max upload size (100MB) |\n| `GLMACP_MAX_FILE_VIEW_SIZE` | `10485760` | Max file view size (10MB) |\n| `GLMACP_TUNNEL` | `false` | **v1.0.3** Auto-start cloudflared tunnel (`auto`, `true`, `yes`) |\n| `GLMACP_TUNNEL_URL` | *(none)* | **v1.0.3** Reuse an existing tunnel URL |\n\n## Documentation\n\n- **[skills/acp/SKILL.md](./skills/acp/SKILL.md)** - Agent skill file (v1.0.6, canonical agent reference)\n- **[ACP-Specification.md](./ACP-Specification.md)** - Full protocol specification\n- **[ACP-Human-Guide.md](./ACP-Human-Guide.md)** - Setup guide for human operators\n- **[OpenAPI.yaml](./OpenAPI.yaml)** - OpenAPI 3.0 specification\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────┐\n│                      AI Agent                            │\n│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │\n│  │ File Ops    │  │ Shell Exec  │  │ LLM Calls   │     │\n│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘     │\n│         │                │                │             │\n│         └────────────────┼────────────────┘             │\n│                          │                              │\n│                          ▼                              │\n│  ┌───────────────────────────────────────────────┐     │\n│  │              ACP Client Library               │     │\n│  │  log_action() | check_stop() | complete()     │     │\n│  └───────────────────────┬───────────────────────┘     │\n└──────────────────────────┼──────────────────────────────┘\n                           │ HTTP REST / JSON-RPC 2.0\n                           ▼\n┌─────────────────────────────────────────────────────────┐\n│                    ACP Server                            │\n│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │\n│  │ REST API    │  │ Web UI      │  │ Storage     │     │\n│  └─────────────┘  └─────────────┘  └─────────────┘     │\n│  ┌─────────────┐  ┌─────────────┐                       │\n│  │ A2A/JSON-   │  │ Agent       │  (v1.0.4)             │\n│  │ RPC Layer   │  │ Registry    │                       │\n│  └─────────────┘  └─────────────┘                       │\n└─────────────────────────────────────────────────────────┘\n                           │\n                           ▼\n                    Human Operator\n                    (Browser/Dashboard)\n```\n\n## Use Cases\n\n1. **Development Agents** - Monitor what files your coding agent is touching\n2. **Research Agents** - Track web searches and LLM interactions\n3. **Task Automation** - See progress of long-running automation tasks\n4. **Safety/Control** - Intervene when agents go off-track\n5. **Multi-Agent Systems** - Coordinate and observe multiple agents sharing one session\n\n## License\n\nMIT\n\n## Author\n\nVTSTech","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvtstech%2Facp-agent-control-panel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvtstech%2Facp-agent-control-panel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvtstech%2Facp-agent-control-panel/lists"}