Squan

Multi-agent AI development command center with 53 built-in tools and 17 messaging platforms.

Squan orchestrates multiple AI agents working in parallel across your git repositories. Dispatch agents from a desktop app or control them from Telegram, Discord, Slack, WhatsApp, and 13+ other messaging platforms.

📥 Download • 📖 Guides • 🌐 Website • 📺 Demo

🎉 What's New in v2.8.4

🔧 Improvements

Auto Port Detection: Squan now automatically finds an available port if 3001 is in use (no more "port already in use" errors)
Graceful Server Startup: Better error handling and logging during server initialization
Improved Stability: Fixed server spawning to use Electron's bundled Node runtime

What's New in v2.8.0

🔧 53 Built-in Tools Across 7 Categories

Every agent automatically gets access to a comprehensive toolkit:

Category	Count	Tools
📁 Filesystem	15	`read_file`, `write_file`, `edit_file`, `list_directory`, `search_files`, `file_tree`, `file_stat`, `glob_files`, `diff_files`, `copy_file`, `move_file`, `delete_file`, `archive_create`, `archive_extract`, `file_checksum`
🌿 Git	12	`git_status`, `git_diff`, `git_log`, `git_branch`, `git_commit`, `git_stash`, `git_blame`, `git_cherry_pick`, `git_merge`, `git_tag`, `git_remote`, `git_reset`
🔍 Code Analysis	7	`find_symbols`, `find_references`, `code_metrics`, `dependency_graph`, `lint_check`, `ast_outline`, `find_duplicates`
🌐 Network	7	`fetch_url`, `search_web`, `http_request`, `download_file`, `dns_lookup`, `url_screenshot`, `check_port`
🗄️ Database	4	`query_sqlite`, `list_tables`, `describe_table`, `query_csv`
💻 System	8	`system_info`, `env_vars`, `process_list`, `disk_usage`, `network_info`, `kill_process`, `open_url`, `clipboard`
🤝 Agent Coordination	8	`delegate_task`, `ask_agent`, `share_context`, `read_shared_context`, `create_skill`, `notify_user`, `request_review`, `task_complete`

Total: 53 tools — no configuration needed. Agents discover and use them automatically.

💬 17 Messaging Platform Gateway

Control your agents from any messaging platform:

📱 Telegram	💬 Discord	💼 Slack	📞 WhatsApp	🔒 Signal	🌐 Matrix
👥 Mattermost	🏢 Teams	✉️ Email	🇨🇳 WeChat	💚 WeCom	🔔 DingTalk
🦅 Feishu	🟢 LINE	🐧 QQ Bot	🍎 iMessage	💻 IRC

Unified Gateway Architecture:

Each platform has a dedicated adapter (WebSocket, long poll, webhook, SMTP/IMAP)
Single router manages sessions and maps platform users to Squan agents
8 slash commands work identically on every platform: /new, /agents, /switch, /status, /stop, /clear, /models, /help

Example (Telegram):

You: /new Write a FastAPI endpoint for user auth
Bot: ✅ Agent #42 dispatched! Building auth endpoint...
     [streaming response with tool calls]
     
You: Add JWT token refresh
Bot: 🔧 Working on it...
     [continues with follow-up]

See Platform Setup Guide for configuration.

⚡ Core Features

🤖 Multi-Agent Orchestration

Dispatch multiple AI agents to work on tasks simultaneously
Each agent works in an isolated git worktree — no merge conflicts
Monitor agent progress in real-time via chat interface
Follow-up conversations — agents stay alive after completion, ask clarifying questions or give more instructions
Multi-model support — Anthropic, OpenAI, Gemini, Ollama, or any OpenAI-compatible endpoint

📋 Visual Kanban Board

5-column workflow: Open → In Progress → PR Review → Landed → Cancelled
Auto-updates as agents complete work
Inline agent status and quick actions on cards
"Mark Complete" button to advance tasks manually

💬 Interactive Agent Chat

Real-time streaming responses with tool call cards (expandable JSON)
Always-visible follow-up input — continue conversations after completion
Completion action bar: Continue Chatting or Mark Complete & Advance

🔌 MCP Extension Support

Connect to 1000+ community MCP servers — databases, Slack, Jira, GitHub Issues, Figma, Notion, Stripe, and more
Agents automatically discover and use MCP tools alongside the 53 built-in tools
Supports both stdio (CLI-based) and HTTP transports

📁 Everything-as-Code

All project state stored in .squan/ directory inside your repo
Tasks are markdown files with YAML frontmatter
Every change is a git commit — full audit trail
Version-controlled task templates, agent charters, and project docs

🖥 Desktop App + Web Access

Electron-based — double-click to run (no terminal, no npm, no Node.js required)
Or access via browser at http://localhost:3001 (Docker deployment)

🔗 GitHub Integration

Browse and clone repos from your GitHub account
Create new repos directly from Squan
Auto-create PRs from agent work with one click

📊 Monitoring & Analytics

Events stream — real-time activity log of all agents
Metrics dashboard — success rates, task completion stats
Cost tracking — token usage and API spend per agent
Live status bar with connection health, agent count, and current spend

🛡️ Code Signing

Windows binaries signed with SSL.com eSigner — no SmartScreen warnings
macOS binaries signed and notarized with Apple Developer ID — no Gatekeeper blocks
Fully automated via GitHub Actions

🚀 Quick Start

Option 1: Download Binary (Easiest)

📥 Download for Windows or macOS

Download the signed binary for your platform
Run Squan.exe (Windows) or open Squan.app (macOS)
The embedded server starts automatically
Enter your Anthropic API key in Settings → AI Provider
Create a project, add tasks, dispatch agents!

Option 2: Build from Source

git clone https://github.com/tarvitave/squan.git
cd squan
npm install
npm start

Builds the server, client, and Electron shell, then launches the app.

Option 3: Docker (Web Deployment)

git clone https://github.com/tarvitave/squan.git
cd squan
cp .env.example .env  # Add your API keys
docker-compose up -d

Access at http://localhost:80.

📖 Documentation

Full Guides — Comprehensive documentation for all 53 tools + 17 messaging platforms with setup examples
Tutorial 1: UI Walkthrough — Step-by-step guide using the graphical interface
Tutorial 2: CLI & Console — Power-user guide via the sq> console
Architecture Overview — How the tool registry and messaging gateway work

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                   Squan Desktop App                     │
│                    (Electron 33)                        │
│  ┌────────────────────────────────────────────────────┐│
│  │        React Frontend (TypeScript + Tailwind)      ││
│  │  • Kanban Board • Agent Chat • Settings • Metrics ││
│  └──────────────────┬─────────────────────────────────┘│
│                     │ WebSocket + REST API             │
│  ┌──────────────────▼─────────────────────────────────┐│
│  │      Express Server (Node.js + TypeScript)         ││
│  │  • Process Manager (spawns agent child processes)  ││
│  │  • SQLite cache (real-time state sync)             ││
│  │  • .squan/ filesystem engine (source of truth)     ││
│  │  • MCP client (connects to extension servers)      ││
│  │  • Gateway router (17 messaging platform adapters) ││
│  └──────────────────┬─────────────────────────────────┘│
└─────────────────────┼─────────────────────────────────┘
                      │
         ┌────────────┴───────────┬───────────────┐
         │                        │               │
         ▼                        ▼               ▼
  ┌─────────────┐      ┌─────────────┐    ┌─────────────┐
  │  Agent #1   │      │  Agent #2   │    │  Telegram   │
  │ (worktree)  │      │ (worktree)  │    │   Gateway   │
  ├─────────────┤      ├─────────────┤    │ (long poll) │
  │• 53 tools   │      │• 53 tools   │    └─────────────┘
  │• MCP ext.   │      │• MCP ext.   │
  │• Claude API │      │• GPT-4o API │
  └─────────────┘      └─────────────┘

How Agents Work

Dispatch — Create a task on the kanban board, click "Dispatch Agent"
Isolation — Squan creates a git worktree and writes CLAUDE.md with task instructions
Spawn — A child process starts, running the agent with your chosen AI model
Work — The agent uses the 53 built-in tools + any MCP extensions to complete the task
Stream — Real-time updates appear in the agent chat (tool calls, file edits, commits)
Complete — Agent signals task_complete or you click "Mark Complete"
Follow-up — Continue chatting with the agent or advance the kanban card to PR Review

Everything-as-Code: The `.squan/` Directory

your-project/
├── .squan/
│   ├── config.yaml              # Project settings (workspace path, default model, etc.)
│   ├── board/                   # Kanban board (5 columns)
│   │   ├── open/
│   │   │   └── 001-add-auth.md  # Task = markdown file with YAML frontmatter
│   │   ├── in_progress/
│   │   ├── pr_review/
│   │   ├── landed/
│   │   └── cancelled/
│   ├── charters/                # Agent roles & knowledge bases
│   ├── templates/               # Reusable task templates (standby tasks)
│   └── docs/                    # Project documentation
├── src/
└── package.json

Every task, agent status change, and completion is a git commit — full auditability.

🛠️ Tech Stack

Layer	Technology
Desktop Shell	Electron 33
Frontend	React 19 + TypeScript + Vite 5
Styling	Tailwind CSS 4 + Lucide icons
Backend	Express + TypeScript
Database	SQLite (libsql) — cache layer only
State Source of Truth	`.squan/` files in git
Agent Runtime	Multi-provider: Anthropic, OpenAI, Gemini, Ollama, OpenAI-compatible
Tool Ecosystem	53 built-in + MCP (Model Context Protocol) extensions
Messaging Gateway	17 platform adapters (WebSocket, HTTP, IMAP/SMTP)
Build & Package	electron-forge + GitHub Actions
Code Signing	SSL.com (Windows) + Apple Developer ID (macOS)
Deployment	Docker + Docker Compose

⌨️ Keyboard Shortcuts

Shortcut	Action
`⌘K` / `Ctrl+K`	Command palette
`⌘B` / `Ctrl+B`	Toggle sidebar
`⌘,` / `Ctrl+,`	Settings
`⌘` / `Ctrl+` `	Toggle Claude Code panel
`⌘1` – `⌘6`	Switch views (Agents, Kanban, Metrics, Events, Costs, Console)
`Esc`	Close modals / cancel actions

🔧 Configuration

In-App Settings

Setting	Location	Description
API Keys	Settings → AI Provider	Add Anthropic, OpenAI, Gemini, or Ollama credentials
OAuth Sign-In	Settings → AI Provider	Authenticate with your Anthropic Pro/Max subscription
GitHub Token	Settings → GitHub	Personal access token for repo browsing and PR creation
MCP Extensions	Settings → Extensions	Add MCP servers (stdio or HTTP) for databases, APIs, tools
Workspace Path	Settings → Workspace	Default: `~/squan-workspace` (where repos are cloned)
Font Size	Settings → Appearance	UI scaling

Environment Variables

Variable	Description	Default
`PORT`	Server port	`3001`
`DB_URL`	SQLite database path	`file:./squansq.db`
`JWT_SECRET`	Authentication secret	`squansq-dev-secret`
`ANTHROPIC_API_KEY`	Default Anthropic key	(none)
`OPENAI_API_KEY`	Default OpenAI key	(none)

📦 Building from Source

Development Mode

npm run dev          # Server (:3001) + Client (:3000) with hot reload

Production Binary

npm run package      # Creates portable binary at ~/squan-dist/
npm run make         # Creates installers (.exe, .dmg)

Build Output

Platform	Format	Location
Windows	ZIP (portable)	`squan-dist/Squan-<version>-win64.zip`
Windows	Squirrel installer	`out/make/squirrel.windows/x64/`
macOS (Intel)	DMG	`squan-dist/Squan-<version>-macos-x64.dmg`
macOS (Apple Silicon)	DMG	`squan-dist/Squan-<version>-macos-arm64.dmg`

📊 Project Stats (v2.8.4)

53 built-in tools across 7 categories
17 messaging platform integrations
12,257 lines of new code in v2.8.x series
36 new TypeScript files (tool registry + gateway)
4 AI providers supported (Anthropic, OpenAI, Gemini, Ollama)
1000+ MCP servers available in the community
Zero SmartScreen warnings on Windows (signed)
Zero Gatekeeper blocks on macOS (signed & notarized)

🤝 Contributing

Squan is open source (Apache-2.0). Contributions welcome!

Fork the repo
Create a feature branch: git checkout -b feat/my-feature
Commit changes: git commit -am 'Add amazing feature'
Push to the branch: git push origin feat/my-feature
Open a Pull Request

📄 License

Apache-2.0

See LICENSE for full text.

👤 Author

Colin Wynd

Website: squan.dev
GitHub: @tarvitave

🔗 Links

Download Squan — Signed binaries for Windows & macOS
Read the Guides — Full documentation for all 53 tools + 17 platforms
GitHub Releases — Changelog and version history
Report Issues — Bug reports and feature requests

Built with ❤️ by the Squan team

Name		Name	Last commit message	Last commit date
Latest commit History 185 Commits
.github/workflows		.github/workflows
.squan		.squan
.vscode		.vscode
assets		assets
client		client
data		data
docs		docs
electron		electron
scripts		scripts
server		server
vscode-extension		vscode-extension
.env.example		.env.example
.gitignore		.gitignore
.mcp.json		.mcp.json
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
entitlements.plist		entitlements.plist
forge.config.ts		forge.config.ts
package-lock.json		package-lock.json
package.json		package.json
slides.html		slides.html
vite.main.config.ts		vite.main.config.ts
vite.preload.config.ts		vite.preload.config.ts
vite.renderer.config.ts		vite.renderer.config.ts

Folders and files

Latest commit

History

Repository files navigation