{"id":50783644,"url":"https://github.com/niasand/miniagent","last_synced_at":"2026-06-12T05:32:30.092Z","repository":{"id":361539270,"uuid":"1239736993","full_name":"niasand/miniagent","owner":"niasand","description":"Local control plane for CLI agents — orchestrate Codex CLI, Claude Code, and Trae CLI behind a unified interface","archived":false,"fork":false,"pushed_at":"2026-05-31T04:32:56.000Z","size":923,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-31T06:16:05.309Z","etag":null,"topics":["acp","agent","cli","hono","orchestration","react","sqlite","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/niasand.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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-15T11:44:27.000Z","updated_at":"2026-05-31T04:33:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/niasand/miniagent","commit_stats":null,"previous_names":["niasand/miniagent"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/niasand/miniagent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niasand%2Fminiagent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niasand%2Fminiagent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niasand%2Fminiagent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niasand%2Fminiagent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/niasand","download_url":"https://codeload.github.com/niasand/miniagent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niasand%2Fminiagent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34231214,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"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":["acp","agent","cli","hono","orchestration","react","sqlite","typescript"],"created_at":"2026-06-12T05:32:29.274Z","updated_at":"2026-06-12T05:32:30.083Z","avatar_url":"https://github.com/niasand.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MiniAgent\n\n\u003e Local control plane for CLI agents — run, manage, and bridge Codex CLI, Claude Code, and Trae CLI to Web UI and chat channels.\n\n[中文文档](./README.zh-CN.md)\n\n## What It Does\n\nMiniAgent is **not** another AI agent. It's a **control plane** that orchestrates existing CLI agents (Codex CLI, Claude Code, Trae CLI) behind a unified interface:\n\n- **Multi-session management** — run multiple agent instances in parallel, each with its own workspace and context.\n- **Streaming output** — real-time markdown, tool calls, thinking process, and task status delivered to Web UI or chat channels.\n- **Event-sourced persistence** — all agent output is appended to an append-only EventStore before delivery. Nothing is lost on crash or reconnect.\n- **Chat channel bridge** — connect agents to Feishu, QQ, Telegram, WeChat, DingTalk, Discord, WeCom via pluggable channel adapters.\n- **Context lifecycle** — automatic context budget monitoring, compaction via ContextPack, and cross-agent handoff.\n- **Scheduled tasks** — one-shot and cron-triggered agent runs with deduplication and concurrency policies.\n\n## Architecture\n\n```\nWeb / Chat Channel\n  → Command Router\n  → Session / Run / Task State Machine\n  → RuntimeSupervisor\n  → AgentRuntimeAdapter\n  → EventStore (append-only)\n  → Projectors → Outbox\n  → Delivery → Web / Chat Channel\n```\n\n**Key invariants:**\n\n- Agent output is stored **before** it is displayed or delivered.\n- `events.global_seq` is the single cursor for replay, reconnect, and recovery.\n- Projectors and Outbox are asynchronous — the hot path stays thin.\n- Retrying creates a new `AgentRun`; handoff creates a new `Session`.\n\nSee [ARCHITECTURE.md](./ARCHITECTURE.md) for the full specification.\n\n## Tech Stack\n\n| Layer | Technology |\n|-------|-----------|\n| Frontend | React 19, Tailwind CSS 4, Zustand, TanStack Query |\n| Backend | Hono, better-sqlite3 (WAL), TypeScript |\n| Agent Protocol | ACP (Agent Client Protocol) via stdio JSON-RPC |\n| Build | Vite 8, TypeScript 6 |\n| Testing | Vitest, Playwright |\n| Runtime | Node.js ≥ 22 |\n\n## Getting Started\n\n### Prerequisites\n\n- Node.js ≥ 22\n- At least one supported CLI agent installed (Codex CLI, Claude Code, or Trae CLI)\n\n### Install \u0026 Run\n\n```bash\n# Install dependencies\nnpm install\n\n# Run database migrations (first time or after schema changes)\nnpm run db:migrate\n\n# Start the API server (port 7273)\nnpm run dev:api\n\n# Start the frontend dev server (port 7272)\nnpm run dev\n```\n\nOpen http://127.0.0.1:7272 to access the Web console.\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `MINIAGENT_API_PORT` | `7273` | API server port |\n\n## Project Structure\n\n```\nsrc/\n├── client/                  # React frontend\n│   ├── api/                 # API client hooks\n│   ├── components/          # UI components\n│   │   ├── ui/              # Primitives (Button, Badge, Tabs)\n│   │   ├── app-shell.tsx    # Main app layout\n│   │   ├── channel-card.tsx # Channel status cards\n│   │   └── controls.tsx     # Session controls\n│   └── App.tsx\n├── server/\n│   ├── channels/            # Chat channel adapters\n│   │   ├── feishu.ts        # Feishu/Lark\n│   │   ├── qq.ts            # QQ\n│   │   ├── telegram.ts      # Telegram\n│   │   ├── wechat.ts        # WeChat\n│   │   ├── dingtalk.ts      # DingTalk\n│   │   ├── discord.ts       # Discord\n│   │   └── wecom.ts         # WeCom\n│   ├── db/                  # SQLite migrations\n│   ├── http/                # Hono HTTP server \u0026 routes\n│   ├── runtime/\n│   │   ├── acp/             # ACP protocol driver \u0026 JSON-RPC\n│   │   ├── supervisor.ts    # Process lifecycle management\n│   │   ├── permission-policy.ts\n│   │   └── text-delta-batcher.ts\n│   ├── security/            # Workspace policy \u0026 secret redaction\n│   ├── services/            # Business logic\n│   │   ├── context.ts       # Context budget \u0026 ContextPack\n│   │   ├── delivery.ts      # Outbox delivery worker\n│   │   ├── handoff.ts       # Cross-agent handoff\n│   │   ├── inbound.ts       # Command routing\n│   │   ├── knowledge.ts     # Knowledge management\n│   │   ├── scheduler.ts     # Cron \u0026 one-shot tasks\n│   │   └── workspace.ts     # Workspace management\n│   └── stores/              # SQLite data access layer\n│       ├── event-store.ts   # Append-only event log\n│       ├── session-store.ts # Session \u0026 run state\n│       ├── message-store.ts # Projected messages\n│       ├── outbox-store.ts  # Delivery queue\n│       └── ...\n└── shared/                  # Shared types \u0026 utilities\n```\n\n## Supported Channels\n\n| Channel | Adapter | Notes |\n|---------|---------|-------|\n| Web UI | ✅ Built-in | SSE streaming, no extra config |\n| Feishu / Lark | ✅ WebSocket | App ID + Secret |\n| QQ | ✅ WebSocket | App ID + Secret |\n| Telegram | ✅ Long polling | Bot Token |\n| WeChat | ✅ Long polling | QR code login |\n| DingTalk | ✅ Webhook | Client ID + Secret |\n| Discord | ✅ WebSocket | Bot Token |\n| WeCom | ✅ Webhook | Bot ID + Secret |\n\nChannel status is reflected in real-time: **Connected** (adapter running), **Configured** (credentials saved, not started), or **Available** (needs configuration).\n\n## Development\n\n```bash\n# Run tests\nnpm test\n\n# Run tests in watch mode\nnpm run test:watch\n\n# Browser (E2E) tests\nnpm run test:browser\n\n# Type checking\nnpm run typecheck\n\n# Build for production\nnpm run build\n```\n\n## License\n\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fniasand%2Fminiagent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fniasand%2Fminiagent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fniasand%2Fminiagent/lists"}