{"id":50319584,"url":"https://github.com/supertorpe/agentstrator","last_synced_at":"2026-05-29T02:30:53.425Z","repository":{"id":356907403,"uuid":"1233322770","full_name":"supertorpe/agentstrator","owner":"supertorpe","description":"Containerized AI agent framework with modular packages and bridge services (Telegram/Discord), powered by OpenCode.","archived":false,"fork":false,"pushed_at":"2026-05-22T18:28:00.000Z","size":186,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-22T21:54:15.477Z","etag":null,"topics":["agent-browser","ai-agents","bmalph","caveman","context-mode","dev-containers","discord","docker","gentle-ai","graphify","lean-ctx","mempalace","oh-my-openagent","opencode","openspec","playwright-cli","rtk","superpowers","telegram"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/supertorpe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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-05-08T20:46:14.000Z","updated_at":"2026-05-22T18:28:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/supertorpe/agentstrator","commit_stats":null,"previous_names":["supertorpe/agentstrator"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/supertorpe/agentstrator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supertorpe%2Fagentstrator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supertorpe%2Fagentstrator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supertorpe%2Fagentstrator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supertorpe%2Fagentstrator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/supertorpe","download_url":"https://codeload.github.com/supertorpe/agentstrator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supertorpe%2Fagentstrator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33634611,"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-05-29T02:00:06.066Z","response_time":107,"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":["agent-browser","ai-agents","bmalph","caveman","context-mode","dev-containers","discord","docker","gentle-ai","graphify","lean-ctx","mempalace","oh-my-openagent","opencode","openspec","playwright-cli","rtk","superpowers","telegram"],"created_at":"2026-05-29T02:30:51.837Z","updated_at":"2026-05-29T02:30:53.417Z","avatar_url":"https://github.com/supertorpe.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agentstrator\n\nAgentstrator runs [OpenCode](https://opencode.ai) as a **sidecar container**, capable of attaching to and controlling pre-existing development containers without needing to modify their images to add AI agents, skills, commands, or packages.\nIt also works standalone, running OpenCode directly without attaching to any dev container — for working on local projects, orchestrating workflows, or using agent packages independently. No need to install OpenCode, SDKs, or agent packages inside your project images — the agent lives alongside them, not inside them.\n\n## How it works\n\n```\n ┌────────────────────────────────────────────────────────┐\n │ ┌────────────────┐       ┌─────────────────────────┐   │\n │ │┌───────────────┴─┐     │ ┌───────────────────────┴─┐ │\n │ ││  Dev Container  │     │ │ agentstrator:runtime    │ │\n │ ││   (your app)   ◄┼─────┼─┼  - opencode             │ │\n │ └┼   No changes    │     │ │  - packages (optional)  │ │\n │  │     needed      │     └─┤    tools, workflows...  │ │\n │  └─────────────────┘       └─▲──────────┬───────▲────┘ │\n │                              │          │       │      │\n │                              │          │       │      │\n │                              │    ┌─────▼────┐  │      │\n │                              │    │          │  │      │\n │                              │    │ Registry │  │      │\n │                              │    │          │  │      │\n │                              │    └─▲──────▲─┘  │      │\n │                              │      │      │    │      │\n │                              │      │      │    │      │\n │                            ┌─┴──────┴─┐┌───┴────┴─┐    │\n │                            │ Telegram ││ Discord  │    │\n │                            │  bridge  ││  bridge  │    │\n │                            └──────────┘└──────────┘    │\n └────────────────────────────────────────────────────────┘\n```\n\n## Install\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/supertorpe/agentstrator/main/install.sh | bash\n```\n\nRun `agentstrator setup` anytime for an interactive configuration where you choose which packages to install or uninstall.\n\n## Usage\n\n```bash\nagentstrator                    # Show a menu to choose the running mode\nagentstrator --cli              # Launch OpenCode in client mode\nagentstrator --srv              # Launch OpenCode in server mode (registers with registry)\nagentstrator --dev CONTAINER    # Attach to an existing dev container\nagentstrator --shell            # Open a shell in a new agentstrator container, mapping current directory\nagentstrator setup              # Re-run interactive setup\nagentstrator install \u003cpkg\u003e      # Install a specific package\nagentstrator remove \u003cpkg\u003e       # Remove a package\nagentstrator rebuild            # Rebuild all packages\nagentstrator upgrade            # Check GitHub for updates, download and rebuild\nagentstrator status             # Check current vs latest version\nagentstrator services \u003ccmd\u003e     # Manage bridge services (start/stop/logs)\n```\n\n## Image layers\n\n```\nagentstrator:base       ← debian-bookworm + system tools (curl, git, jq, python, node)\n  └─ agentstrator:core  ← opencode-ai only\n       └─ agentstrator:runtime  ← core + all installed packages merged into one image\n```\n\nThe `runtime` image is what runs as the sidecar. Base is stable and never rebuilt. Core and runtime are rebuilt on `upgrade` and `rebuild`.\n\n## Packages\n\nAgentstrator packages install inside the Docker image, not on the host. They're available to the agent without modifying your development containers. See [`adding-packages.md`](adding-packages.md) to add new ones.\n\n### Token Compression \u0026 Monitoring\n| Package        | Description                                     |\n|----------------|-------------------------------------------------|\n| [`rtk`](https://github.com/rtk-ai/rtk)          | Filters and compresses command outputs          |\n| [`lean-ctx`](https://github.com/yvgude/lean-ctx)          | Reduces LLM token consumption up to 99%         |\n| [`context-mode`](https://github.com/mksglu/context-mode)  | Context window optimization                     |\n| [`caveman`](https://github.com/JuliusBrussee/caveman)      | Cuts 65% of tokens by talking like caveman      |\n| [`tokscale`](https://github.com/junhoyeo/tokscale)         | Token usage tracker and visualization dashboard |\n| [`tokenscope`](https://github.com/ramtinJ95/opencode-tokenscope) | Token usage analysis and cost tracking          |\n\n### Workflows \u0026 Orchestration\n| Package           | Description                                        |\n|-------------------|----------------------------------------------------|\n| [`continues`](https://github.com/yigitkonur/cli-continues)       | Resume coding sessions                             |\n| [`superpowers`](https://github.com/obra/superpowers)     | Complete software development methodology          |\n| [`oh-my-openagent`](https://github.com/code-yeongyu/oh-my-openagent) | Advanced orchestration with workflow automation    |\n| [`ijfw`](https://gitlab.com/therealseandonahoe/ijfw)       | Memory, routing, audits, workflow                   |\n| [`gentle-ai`](https://github.com/Gentleman-Programming/gentle-ai)       | SDD workflow, memory, and skills                   |\n| [`nwave`](https://github.com/nWave-ai/nWave)           | AI agents that guide you from idea to working code |\n| [`openspec`](https://github.com/Fission-AI/OpenSpec)        | Spec-driven development                            |\n| [`bmalph`](https://github.com/LarsCowe/bmalph)          | BMAD-METHOD with Ralph                             |\n| [`agent-skills`](https://github.com/addyosmani/agent-skills)    | Engineering skills and workflows                   |\n\n### Memory / Knowledge / Understanding\n| Package     | Description |\n|-------------|---------------------------------------------------|\n| [`graphify`](https://github.com/safishamsi/graphify)  | Knowledge graph builder                           |\n| [`mempalace`](https://github.com/MemPalace/mempalace) | AI memory system                                  |\n| [`agentmemory`](https://github.com/rohitg00/agentmemory) | Persistent memory for AI coding agents        |\n| [`codegraph`](https://github.com/colbymchenry/codegraph)   | Semantic knowledge graph of codebases       |\n| [`codedna`](https://github.com/Larens94/codedna)   | In-source annotation protocol for AI agents       |\n| [`leankg`](https://github.com/FreePeak/LeanKG)    | Lightweight knowledge graph with MCP for AI tools |\n\n### Developer Tools\n| Package          | Description            |\n|------------------|------------------------|\n| [`playwright-cli`](https://github.com/microsoft/playwright-cli) | Browser automation     |\n| [`agent-browser`](https://github.com/vercel-labs/agent-browser)  | Browser automation     |\n| [`sentrux`](https://github.com/sentrux/sentrux)        | AI code quality sensor |\n\n## Bridges: Telegram \u0026 Discord\n\nAgentstrator includes optional bridge services that connect a Telegram bot and/or a Discord bot to your running OpenCode instances. Configure them during `agentstrator setup` and start them with:\n\n```bash\nagentstrator services start\n```\n\nAll communication goes through the registry, so the bridges work in both single-node and multi-node setups.\n\n## Setting Up Bots\n\n### Telegram Bot Setup\n\n1. **Create a bot via @BotFather:**\n   - Open Telegram and search for `@BotFather`\n   - Send `/newbot`\n   - Choose a display name (e.g., \"My AI Assistant\")\n   - Choose a username ending in `bot` (e.g., `my_ai_assistant_bot`)\n   - BotFather will give you a token like `123456789:ABCdef...`\n\n2. **Configure the token:**\n   - During `agentstrator setup`, you'll be prompted for the Telegram Bot Token\n   - Or edit `$HOME/.agentstrator/.env` directly:\n     ```\n     TELEGRAM_BOT_TOKEN=your-bot-token-here\n     ```\n\n3. **Restrict access (optional):**\n   - Set `TELEGRAM_ALLOWED_USERS` to comma-separated Telegram usernames (without `@`):\n     ```\n     TELEGRAM_ALLOWED_USERS=username1,username2\n     ```\n   - Leave empty to allow all users\n\n4. **Start the service:**\n   ```bash\n   ./agentstrator services start\n   ```\n\n5. **Use the bot:**\n   - Open a chat with your bot in Telegram\n   - Send `/agents` to see available agents\n   - Select an agent, mode, and session to start interacting\n\n### Discord Bot Setup\n\n1. **Create a Discord Application:**\n   - Go to the [Discord Developer Portal](https://discord.com/developers/applications)\n   - Click \"New Application\" and give it a name\n   - Go to the \"Installation\" section in the left sidebar\n   - Select \"None\" in \"Install Link\" dropdown\n   - Click \"Save changes\"\n   - Go to the \"Bot\" section in the left sidebar\n   - Uncheck \"Public Bot\"\n   - Check \"Presence Intent\", \"Server Members Intent\" and \"Message Content Intent\"\n   - Click \"Reset Token\" and copy the token generated into a safe place\n   - Click \"Save changes\"\n\n2. **Invite the bot to your server:**\n   - Go to \"OAuth2\" section in the left sidebar → \"URL Generator\"\n   - Select scopes: `bot`, `applications.commands`\n   - Select bot permissions:\n     - **Text Permissions**: `Send Messages`, `Send Messages in Threads`, `Read Message History`, `Embed Links`, `Attach Files`\n     - **General Permissions**: None required\n   - Copy the generated URL and open it in your browser\n   - Select the server to invite the bot to\n\n3. **Configure the token:**\n   - During `agentstrator setup`, select `discord` and you'll be prompted for the Discord Bot Token and allowed users\n   - Or edit `$HOME/.agentstrator/.env` directly:\n     ```\n     DISCORD_BOT_TOKEN=your-discord-token-here\n     ```\n\n4. **Restrict access (optional):**\n   - Set `DISCORD_ALLOWED_USERS` to comma-separated Discord **user IDs** or usernames:\n     ```\n     DISCORD_ALLOWED_USERS=123456789012345678,username1\n     ```\n   - To find a user ID: enable Developer Mode in Discord (Settings → Advanced → Developer Mode), then right-click a user → \"Copy User ID\"\n   - Leave empty to allow all users\n\n5. **Start the service:**\n   ```bash\n   ./agentstrator services start\n   ```\n\n6. **Use the bot:**\n   - In any channel or DM, use slash commands:\n     - `/agents` - Select an agent to interact with\n     - `/sessions` - View and manage your sessions\n     - `/mode` - Switch the active session mode\n     - `/log` - View session conversation logs\n     - `/help` - Show available commands\n   - **In channels**: Mention the bot with `@bot_name your message` to send messages to the active agent\n   - **In DMs**: Just type your message directly — no mention needed\n\n## Multi-node deployments\n\nAgentstrator supports two modes:\n\n- **Single node** — file-based registry, no external dependencies\n- **Multi node** — registry service for agent discovery across machines\n\nThe multi-node setup runs a registry service (`services/registry/`) that agents register with. Bridges and other agents discover each other through this registry. Configure during `agentstrator setup`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsupertorpe%2Fagentstrator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsupertorpe%2Fagentstrator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsupertorpe%2Fagentstrator/lists"}