Arnav Naval
7729d5957e
Add 12 new routes under /api/twitter that wrap every twikit Client
DM method that exists directly (no inbox listing — twikit has no
high-level method for it). Same gate discipline as the tweet writes:
all sends/deletes/reactions go through pick_writable so only
role=primary accounts can DM on the user's behalf, and DM reads cache
on short TTLs (15s for conversations, 60s for group metadata).
1:1 reactions compute the X-side conversation_id
("{partner_id}-{my_user_id}") inside the route via client.user_id(),
matching twikit's own Message.add_reaction formula; group reactions
pass the group_id directly. The send_dm path inherits twikit's own
user_id() lookup, which is cached after first hit so the bucket cost
is one-time.
- models: SendDMRequest, AddGroupMembersRequest, ChangeGroupNameRequest,
AddDMReactionRequest, AddGroupReactionRequest
- ratelimit: 8 new DEFAULT_BUDGETS entries (send_dm/delete_dm/
dm_conversation/get_group/add_members_to_group/change_group_name/
add_reaction_to_message/remove_reaction_from_message). DM caps are
tight by default — operators dial up via trust_multiplier once
they've observed no 429s
- serializers: message_to_dict (Message + GroupMessage; group_id is
None for 1:1), group_to_dict (members serialized via user_to_dict)
- twitter.py: POST/GET /users/{user_id}/dms, DELETE /dms/{message_id},
POST/DELETE /dms/{message_id}/reaction, POST/GET /groups/{group_id}/dms,
GET /groups/{group_id}, POST /groups/{group_id}/members, PATCH
/groups/{group_id}/name, POST/DELETE /groups/{group_id}/messages/
{message_id}/reaction — plus dm_conversation/get_group cache TTLs
- twitter_mcp_shim: 10 new MCP tools (1:1 reactions only; group
reactions reachable via HTTP route, no shim tool for parity with the
1:1 flow and to keep the tool count modest)
- tests: extend _add_fake_account with the DM AsyncMock surface
(incl. user_id returning "me-1" for conv_id assertions); 23 new
route tests covering happy paths, kwarg forwarding, caching, the
computed 1:1 conv_id ("u-42-me-1"), group reactions (conv_id =
group_id), 429 surfacing on the send_dm bucket, and role gating;
expanded shim tools-list expected to 25 entries and added 16
per-tool dispatch tests
Open Swarm
An Army of AI Agents at Your Fingertips
A locally-running orchestrator for managing multiple agents in parallel.
Launch, monitor, and coordinate entire swarms of coding agents from a single interface.
Why Open Swarm?
Running agents in a terminal works fine for one task. But when you're juggling five agents across different branches, approving tool calls in separate windows, and losing track of who's doing what — it falls apart fast.
- Parallel agents, one screen — Launch as many agents as you need, arranged on a spatial canvas you can pan and zoom freely
- Unified approval workflow — Every tool-use request from every agent surfaces in one place. Approve or deny with a click or a keyboard shortcut.
- Full conversation control — Edit prior messages to fork conversations, navigate between branches, resume closed sessions
- 100% local — Everything runs on your machine. No cloud relay, no telemetry, no third-party backend.
Features
Spatial Dashboard — Infinite canvas with drag-and-drop agent cards, view cards, and embedded browser cards. Create multiple dashboards for different workspaces.
Agent Chat — Full streaming chat interface powered by WebSockets. Real-time token output, cost tracking per session, and persistent history that survives restarts.
Human-in-the-Loop Approvals — Agents request permission before executing tools. Approve or deny individually, or batch-approve from the dashboard. Configurable per-tool permissions (always allow, ask, deny).
Message Branching — Edit any prior message to fork the conversation. Navigate freely between branches without losing context.
Prompt Templates — Build reusable templates with structured input fields. Invoke them inline via / slash commands.
Skills Library — Manage skills that sync directly to ~/.claude/skills/. Browse and install from the official Anthropic skills marketplace.
Tools Library — Configure MCP tool servers (stdio, HTTP, SSE) with automatic tool discovery. Browse the MCP registry and Google's catalog with GitHub star counts. Includes Google Workspace OAuth integration.
Agent Modes — Five built-in modes (Agent, Ask, Plan, View Builder, Skill Builder) plus custom user-defined modes with configurable system prompts and tool restrictions.
Views & Outputs — Create interactive HTML/JS/CSS artifacts rendered in iframes. Supports vibe coding (LLM-generates the view), backend Python execution, auto-run with LLM-generated data, and agent-driven data gathering.
Git Worktree Isolation — Each agent operates in its own git worktree and branch, preventing conflicts between parallel workstreams.
Diff Viewer — Inspect uncommitted changes in any agent's worktree without leaving the app.
Cost Tracking — Real-time USD spend tracking per agent session.
Dark & Light Themes — Full theme support with design tokens.
Keyboard Shortcuts — Navigate between agents, approve/deny requests, and switch pages without touching a mouse.
Quick Start
Desktop App
Download the latest release for macOS from GitHub Releases.
Windows and Linux builds are planned but not yet available.
Development Setup
Prerequisites: Python 3.11+, Node.js 18+, Git
git clone https://github.com/openswarm-ai/openswarm.git
cd openswarm
bash run.sh
This starts the backend (port 8324), frontend (port 3000), and Electron shell together. Once running, set your Anthropic API key in the in-app Settings page.
To run services individually:
bash backend/run.sh # API at http://localhost:8324 — docs at /docs
bash frontend/run.sh # App at http://localhost:3000
Architecture
Electron Shell (desktop wrapper, auto-updater)
├─────────────────────────────────────────────────────────────────────┐
│ │
│ Frontend (React/TypeScript :3000) Backend (FastAPI :8324) │
│ ┌───────────────────────────────┐ ┌───────────────────────┐ │
│ │ Spatial Dashboard Canvas │◄────►│ REST API (/api/*) │ │
│ │ Agent Chat (streaming) │ │ WebSocket (/ws/*) │ │
│ │ Templates / Skills / Tools │ WS │ Agent Manager │ │
│ │ Modes / Views / Commands │◄────►│ └─ claude-agent-sdk│ │
│ │ Settings │ │ MCP Tool Discovery │ │
│ │ Redux Toolkit (state) │ │ JSON File Storage │ │
│ └───────────────────────────────┘ └───────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Configuration
The Anthropic API key is configured in-app via the Settings page — no environment variable needed for normal usage.
For advanced configuration, copy backend/.env.example to backend/.env:
| Variable | Purpose |
|---|---|
BACKEND_PORT |
Backend server port (default: 8324) |
GOOGLE_OAUTH_CLIENT_ID |
Google Workspace integration (Gmail, Calendar, Drive) |
GOOGLE_OAUTH_CLIENT_SECRET |
Google Workspace integration |
APPLE_ID |
macOS code signing & notarization (release builds only) |
APPLE_APP_SPECIFIC_PASSWORD |
macOS notarization (release builds only) |
APPLE_TEAM_ID |
macOS code signing (release builds only) |
GH_TOKEN |
GitHub Releases publishing (release builds only) |
Keyboard Shortcuts
| Key | Action |
|---|---|
D |
Go to Dashboard |
T |
Go to Templates |
1 – 9 |
Open agent by position |
Shift+A |
Approve all pending requests |
Shift+D |
Deny all pending requests |
? |
Show shortcuts help |
Type / in the chat input to invoke prompt templates and skills as slash commands.
Project Structure
backend/
apps/
agents/ Agent lifecycle, streaming, worktree management
dashboards/ Dashboard CRUD and layout persistence
dashboard_layout/ Card positions and spatial canvas state
templates/ Prompt template CRUD
skills/ Skills CRUD (synced to ~/.claude/skills/)
tools_lib/ MCP tool configuration and discovery
modes/ Agent mode definitions
outputs/ Views/outputs, vibe coding, Python executor
settings/ App settings and file browser
health/ Health check endpoint
mcp_registry/ MCP server registry proxy
skill_registry/ Anthropic skills marketplace proxy
config/ FastAPI app configuration
data/ Persistent JSON file storage
frontend/
src/
app/
components/ AppShell, Layout, shared UI
pages/
Dashboard/ Spatial canvas with agent/view/browser cards
AgentChat/ Streaming chat, HITL approvals, branching, diff viewer
Templates/ Template library with structured input fields
Skills/ Skills library, skill builder, registry browser
Tools/ Tool config, MCP discovery, OAuth, registry browser
Modes/ Mode definitions with system prompts
Views/ Output artifacts, code editor, vibe coding
Commands/ Keyboard shortcuts reference
Settings/ App configuration
shared/
state/ Redux slices (agents, dashboards, templates, skills, tools, modes, etc.)
ws/ WebSocket manager
hooks/ Custom hooks
styles/ Theme tokens, global styles
electron/
main.js Electron main process, auto-updater, Python env management
scripts/ Build and notarization scripts
scripts/
build-app.sh Desktop app packaging (electron-builder)
build-python-env.sh Standalone Python 3.13 environment bundler
Tech Stack
Frontend — React 18, TypeScript, Redux Toolkit, Material UI v7, CodeMirror 6, Framer Motion, React Router v7, Webpack 5
Backend — FastAPI, Python 3.11+, Pydantic v2, claude-agent-sdk, Anthropic SDK, WebSockets, httpx
Desktop — Electron 33, electron-builder, electron-updater (auto-updates via GitHub Releases)
Bundled Runtime — Standalone Python 3.13 (via python-build-standalone) so end users don't need Python installed
Contributing
Contributions are welcome. To get started:
- Fork the repository
- Create a feature branch (
git checkout -b feature/your-feature) - Make your changes
- Submit a pull request
Please open an issue first for larger changes so we can discuss the approach.
License
MIT — see LICENSE for details.