---

What is OCTO VEC?

OCTO VEC is an open-source virtual software company — 24 autonomous AI agents that simulate a real dev team. Give a task to the Project Manager and it breaks it down, delegates to specialists, and they collaborate to deliver tested, scanned, documented code.

Not a coding assistant. Not a copilot. A full team — with a PM, Developer, BA, QA, Security Engineer, DevOps, Architect, Researcher, Tech Writer, and 15 more specialist roles you can hire on demand.

you > Build a REST API with auth and write tests

[PM] Breaking down into 3 tasks...
[PM] > TASK-001 assigned to BA (requirements)
[PM] > TASK-002 assigned to Dev (build API)
[PM] > TASK-003 assigned to QA (test suite)

[BA] Requirements written > shared/requirements.md
[Dev] Building API... reading BA specs... writing code...
[Dev] All tests passing (12/12)
[Security] Running SAST scan... 0 critical findings
[QA] Integration tests passing. No issues found.

All tasks completed. Your coffee is getting cold.

---

Meet the Team

9 agents active by default, 15 more available to hire from the Dashboard > Directory.

Management

Role	What They Do
Project Manager	The octopus in charge. Breaks down tasks, assigns work, tracks progress
Product Owner	Backlog prioritization, user stories, stakeholder alignment
Scrum Master	Sprint planning, standup facilitation, agile process management

Engineering

Role	What They Do
Senior Developer	Full-stack production code (Python, JS, TS), tests, bug fixes
Frontend Developer	React, Vue, Angular — UI components, responsive layouts, state management
Backend Developer	APIs, microservices, databases, server-side logic
Mobile Developer	React Native, Flutter — cross-platform mobile apps
Solutions Architect	System design, database schemas, API contracts, tech stack decisions
DevOps Engineer	CI/CD pipelines, Dockerfiles, Kubernetes, deployment configs
SRE	Monitoring, incident response, reliability, performance optimization

Data & AI

Role	What They Do
Data Engineer	ETL pipelines, data warehousing, streaming architectures
Database Administrator	Schema design, query optimization, backup strategies, migrations
ML/AI Engineer	Model training, inference pipelines, embeddings, RAG systems
Data Analyst	Dashboards, metrics, SQL queries, business intelligence reports

Quality & Security

Role	What They Do
QA Engineer	Test plans, test cases, reviews scan reports, validates deliverables
Security Engineer	Vulnerability scans, code audits, OWASP compliance, threat modeling
Compliance Officer	Regulatory compliance, policy enforcement, audit trails

Research & Documentation

Role	What They Do
Business Analyst	Turns vague requests into crystal-clear requirements and user stories
Research Specialist	Technology research, best practices, benchmarks, comparison reports
Technical Writer	API docs, READMEs, user guides, architecture decision records
UI/UX Designer	Wireframes, design systems, user flows, accessibility audits

Operations

Role	What They Do
Release Manager	Release planning, versioning, changelog, deployment coordination
Support Engineer	Issue triage, customer debugging, runbook creation

---

Features

Core

• Real File I/O — Agents read, write, edit, and create actual files on your filesystem
• Agent-to-Agent Messaging — Agents message each other when they need something
• Task Delegation — PM automatically breaks requests into tasks and assigns specialists
• Agent Sandbox — Each agent has a private workspace. Shared workspace for cross-team deliverables
• Git Integration — Agents commit code with their own identity (per-agent git name + email)
• Dynamic Agent Directory — Hire, fire, rename, enable/disable agents at runtime from the dashboard
• 24 Role Templates — PM, Dev, BA, QA, Security, DevOps, Architect, Researcher, Tech Writer, Frontend, Backend, Mobile, Data Engineer, DBA, ML/AI, SRE, Product Owner, UI/UX Designer, Scrum Master, Data Analyst, Release Manager, Compliance Officer, Support Engineer, and more
• Agent Groups — Create team groups for multi-agent conversations
• Web Terminal — Full terminal access from the dashboard (bash, PowerShell, cmd)
• Interrupt & Steer — Stop or redirect a running agent mid-task from the dashboard

Memory

• Three-Tier Memory — Short-term (session), Long-term (daily journals), Super Long-term (permanent knowledge)
• Sunset/Sunrise Lifecycle — Agents journal at end of day, start fresh each morning with context
• Auto-Compaction — Older messages automatically summarized when context gets long

Dashboard

• 10 Real-Time Views — Overview, Kanban, Live Activity, Events, Snoop, Directory, Chat, Network, Finance, Settings
• Live Streaming — Watch agents think, call tools, and generate responses in real time (SSE)
• Three Themes — Dark, Light, Midnight

Mobile App

• Android App — Full mobile dashboard with chat, tasks, agents, and live activity
• QR Code Pairing — Scan from mobile to connect instantly, no manual config
• Push Notifications — Get notified when agents complete tasks or need attention
• Device Management — Link/unlink devices, auto-logout on unlink (WhatsApp-style)

Communication

• 17 Channels — CLI, Telegram, Slack, Discord, WhatsApp, Teams, Matrix, Signal, LINE, IRC, Twitch, Nostr, Google Chat, Mattermost, Feishu, Nextcloud, Synology — all route to the same PM
• DM Support — Slack and Discord bots respond to direct messages too
• Hot-Reload — Change channel credentials from dashboard without restarting

Security

• Automated Scanning — SAST (Semgrep), secret detection (Gitleaks), SCA (Trivy) run after every coding task
• SonarQube — Optional code quality gates integration
• Scan Reports — Markdown reports saved to workspace/shared/reports/

AI & Models

• 22+ LLM Providers — Groq, OpenAI, Anthropic, Google, Mistral, and more
• Per-Agent Models — Give your architect a stronger model, researcher a faster one
• MCP Support — Connect any Model Context Protocol server for extended tools
• Cost Tracking — Per-agent token usage and USD cost in the Finance dashboard

---

Why OCTO VEC?

Most AI coding tools give you a fast code generator. OCTO VEC gives you a whole company — named agents with distinct roles, persistent memory, and a real-time dashboard to watch them work.

Feature	Copilot	Cursor	Devin	OpenHands	MetaGPT	ChatDev	OCTO VEC
Multi-agent team	—	Yes	—	Yes	Yes	Yes	Yes (24 roles)
Named role simulation (PM, BA, QA, Security…)	—	—	—	—	Partial	Partial	Yes
Three-tier memory (STM/LTM/SLTM)	—	—	—	—	—	—	Yes
Daily lifecycle (Sunset/Sunrise)	—	—	—	—	—	—	Yes
Built-in security scanning (SAST/SCA/Secrets)	Yes	—	—	—	—	—	Yes
Auto-compaction	—	Yes	—	Partial	—	—	Yes
Multi-channel (CLI + 16 platforms)	—	—	Slack	Slack	—	—	Yes (17)
Real-time web dashboard	—	—	Yes	Yes	—	—	Yes (10 views)
Mobile app (Android)	—	—	—	—	—	—	Yes
Self-hosted, vendor-agnostic	—	—	—	Yes	Yes	Yes	Yes
MCP support	Yes	Yes	Yes	Yes	—	—	Yes
Per-agent cost tracking	—	—	—	—	—	—	Yes
Dynamic agent hiring/firing	—	—	—	—	—	—	Yes
Agent groups & team chat	—	—	—	—	—	—	Yes
Web terminal in dashboard	—	—	Yes	Yes	—	—	Yes
QR code mobile pairing	—	—	—	—	—	—	Yes

---

Architecture

+------------------------------------------------------+
|                  HUMAN INTERFACES                     |
|   CLI (readline)   Telegram   Slack   Discord   Web   |
+----------+------------+---------+-------+------+-----+
           |            |         |       |      |
           v            v         v       v      v
+------------------------------------------------------+
|              PM MESSAGE QUEUE (FIFO)                  |
+-------------------------+----------------------------+
                          v
+------------------------------------------------------+
|               PM AGENT (Arjun)                        |
|       Task Tools . Employee Tools . Messaging         |
+--------------------------+---------------------------+
                           | creates tasks + delegates
        +--------+---------+--------+---------+
        v        v         v        v         v
    +------+ +------+  +------+ +------+  +------+
    |  Dev | |  BA  |  |  QA  | |  Sec |  | ...  |
    +------+ +------+  +------+ +------+  +------+
        |        |         |       |         |
        v        v         v       v         v
+------------------------------------------------------+
|           ATP DATABASE (SQLite)                       |
|     tasks . employees . events . messages             |
+------------------------------------------------------+

---

Quick Start

One-liner Install

Works on macOS, Windows & Linux. Installs Node.js and everything else for you.

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/akhil2129/OCTO_VEC/main/scripts/install.sh | bash

Windows (PowerShell):

powershell -c "irm https://raw.githubusercontent.com/akhil2129/OCTO_VEC/main/scripts/install.ps1 | iex"

Or install via npm

Prerequisites: Node.js 20+ and an LLM API key (Groq free tier works great to start)

npm install -g octo-vec
octo-vec start

Or run from source

git clone https://github.com/akhil2129/OCTO_VEC.git
cd OCTO_VEC
npm install
npm start

On first run, OCTO VEC will:

1. Create your data directory (~/.octo-vec on Mac/Linux, %APPDATA%/octo-vec on Windows)
2. Open the dashboard in your browser
3. Walk you through onboarding — set your name, configure an API key

The dashboard opens automatically. Your PM (Arjun) is ready to take requests.

First Message

You > Build me a REST API for a todo app with authentication

Arjun will analyze the request, break it into tasks, and delegate to the right specialists. Watch the magic happen in the Dashboard's Live view.

---

Dashboard

The web dashboard gives you full visibility and control. Access it at the URL printed on startup (includes an authentication key).

View	What It Shows
Overview	Task stats (total, in-progress, completed, failed), active agents, system health
Kanban	Task board with columns: Todo, In Progress, Done, Failed, Cancelled
Live	Real-time agent activity — streaming LLM output, tool calls, agent thinking
Events	Audit trail of all system events, filterable by agent and type
Snoop	Peek into any agent's inbox — see inter-agent messages as they flow
Directory	Employee roster — hire new agents, enable/disable, configure models, manage roles
Chat	Message history with agents. Create groups for team conversations
Network	Visual graph of agent-to-agent communication patterns
Finance	Token usage and cost tracking per agent, per session
Settings	Model providers, API keys, channel credentials, MCP servers, tool config

Themes

Three built-in themes — switch from the sidebar:

• Dark (default)
• Light
• Midnight

---

Communication Channels

Talk to your PM from anywhere. All 17 channels route messages to the same PM agent. Configure any channel from Dashboard > Settings > Channels or via .env variables.

Channel	Protocol	Status
CLI	Built-in terminal	Default
Telegram	grammy	Stable
Slack	Bolt (Socket Mode)	Stable
Discord	discord.js (Gateway)	Stable
WhatsApp	Baileys (Web)	Stable
Microsoft Teams	Bot Framework	Stable
Matrix	matrix-bot-sdk	Stable
Signal	signal-cli REST	Stable
LINE	@line/bot-sdk	Stable
IRC	irc-framework	Stable
Twitch	tmi.js	Stable
Nostr	nostr-tools	Stable
Google Chat	Webhook	Stable
Mattermost	REST API	Stable
Feishu / Lark	Bot API	Stable
Nextcloud Talk	REST API	Stable
Synology Chat	Webhook	Stable

CLI (Default)

Built-in terminal interface. Enabled by default — just type after starting TOWER.

Telegram

1. Create a bot via @BotFather on Telegram
2. Copy the bot token
3. Send a message to your bot, then get your Chat ID from https://api.telegram.org/bot<TOKEN>/getUpdates
4. Configure in Dashboard > Settings > Channels or add to .env:

   TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
   TELEGRAM_CHAT_ID=5253950103
   

5. Click Save & Connect in dashboard (or restart TOWER)

Commands: /board, /queue, /events, /dir, /agents, /help

Slack

1. Create a Slack App at api.slack.com/apps
2. Enable Socket Mode — generate an App-Level Token (xapp-...)
3. Add Bot Token Scopes: chat:write, channels:history, channels:read, im:history
4. Event Subscriptions > Subscribe to bot events: message.channels, message.im
5. Install to workspace — copy the Bot User OAuth Token (xoxb-...)
6. Invite the bot to your channel: /invite @YourBotName
7. Right-click the channel > Copy Channel ID
8. Configure in Dashboard > Settings > Channels or add to .env:

   SLACK_BOT_TOKEN=xoxb-...
   SLACK_APP_TOKEN=xapp-...
   SLACK_CHANNEL_ID=C0ALAM1EMS7
   

Commands: !board, !queue, !events, !dir, !agents, !help

Works in both the authorized channel and direct messages.

Discord

1. Go to Discord Developer Portal > New Application
2. Bot tab > Reset Token > copy the bot token
3. Enable Message Content Intent (Privileged Gateway Intents)
4. OAuth2 > URL Generator > Scopes: bot > Permissions: Send Messages, Read Message History, View Channels
5. Open the generated URL in browser > select your server > Authorize
6. Enable Developer Mode in Discord (Settings > Advanced)
7. Right-click your text channel > Copy Channel ID
8. Configure in Dashboard > Settings > Channels or add to .env:

   DISCORD_BOT_TOKEN=MTIz...
   DISCORD_CHANNEL_ID=1234567890123456789
   

Commands: !board, !queue, !events, !dir, !agents, !help

Works in both the authorized channel and direct messages.

---

CLI Commands

Command	Description
/board	View the task board (Kanban-style from SQLite)
/queue	View PM's message inbox
/events	Last 20 system events
/dir	Employee directory with status and skills
/org	Org chart showing reporting hierarchy
/message <agent> <text>	Send a direct message to any agent
/interrupt <agent> [reason]	Stop a running agent mid-task
/forget	Clear PM conversation history
/live	Toggle live message queue monitor
/reset	Full company reset (requires confirmation)
/quit	Exit the system

Any text that doesn't start with / is sent directly to the PM (Arjun).

---

Configuration

Essential Environment Variables

Variable	Description	Default
VEC_MODEL_PROVIDER	LLM provider (groq, openai, anthropic, google, etc.)	groq
VEC_MODEL	Model identifier	moonshotai/kimi-k2-instruct-0905
VEC_THINKING_LEVEL	Extended thinking (off, minimal, low, medium, high, xhigh)	off
VEC_WORKSPACE	Root workspace directory	./workspace
VEC_CLI_ENABLED	Enable terminal interface (1/0)	1
VEC_DASHBOARD_PORT	Dashboard HTTP port	3000
VEC_PM_PROACTIVE_ENABLED	PM auto-monitors events and sends status updates	0
VEC_PM_PROACTIVE_INTERVAL_SECS	How often PM checks events (seconds)	30
VEC_POST_TASK_SCANS	Auto-run security scans after coding tasks	1
VEC_DEBOUNCE_MS	Message batching window (ms)	1500
VEC_CONTEXT_WINDOW	Model context window size (tokens)	128000
VEC_COMPACT_THRESHOLD	Auto-compact when exceeding this fraction of context	0.75

Provider API Keys

Set in .env or configure in Dashboard > Settings > Models:

GROQ_API_KEY=gsk_...
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_GENERATIVE_AI_API_KEY=AI...

Per-agent model overrides are configurable in the dashboard — give your architect a stronger model while the researcher uses a faster one.

Optional Integrations

# Security scanning (requires Docker)
SONAR_HOST_URL=http://localhost:9000
SONAR_TOKEN=squ_...
SONAR_PROJECT_BASE_KEY=vec

# Web search
SEARXNG_URL=http://localhost:8888

---

How It Works

1. You send a message to the PM via CLI, Telegram, Slack, Discord, or dashboard
2. PM analyzes your request and breaks it into tasks
3. Tasks are assigned to the right specialist agents via the ATP database
4. Agents execute tasks — reading files, writing code, running tests, messaging each other
5. Post-task hooks automatically run security scans on code changes
6. PM monitors progress and reports back to you when everything is done

Each Agent Has

• An inbox for receiving messages (polled every 15 seconds)
• Persistent memory (SLTM + daily LTM journals + in-session STM)
• A tool set scoped to their role (file I/O, git, web search, messaging, etc.)
• A private workspace (workspace/agents/{EMP-ID}/)
• Access to shared workspace (workspace/shared/)

Task Status Flow

pending --> in_progress --> completed
                       --> failed
                       --> cancelled

Tasks stuck in in_progress for >5 minutes are automatically marked as failed by the watchdog.

---

Agent Memory System

Agents don't start from scratch every session.

Three Tiers

Tier	Name	Lifespan	Purpose
SLTM	Super Long-Term Memory	Permanent	Core identity, lasting patterns, hard-won knowledge
LTM	Long-Term Memory	Daily journals	End-of-day summaries — what happened, what was learned
STM	Short-Term Memory	Current session	Active conversation history

Session Lifecycle

Sunset (end of day / stale session):

• Agent reviews their conversation from the previous session
• Writes a daily journal (LTM) summarizing key events
• Optionally updates permanent knowledge (SLTM)
• Conversation history cleared

Sunrise (new session):

• Yesterday's journal + permanent memory automatically loaded
• Agent starts fresh but informed

Auto-Compaction

When an agent's conversation approaches the context window limit, older messages are automatically summarized while preserving recent exchanges. This prevents overflow without losing important context.

---

Security Scanning

When VEC_POST_TASK_SCANS=1 (default), security scans run automatically after coding tasks complete.

Scanner	What It Detects	Tool
SAST	Code vulnerabilities, OWASP Top 10, injection flaws	Semgrep
Secrets	Leaked API keys, tokens, passwords, private keys	Gitleaks
SCA	Vulnerable dependencies, known CVEs in libraries	Trivy
Code Quality	Code smells, coverage gaps, quality gate violations	SonarQube (optional)

Scans run via Docker containers. Reports saved to workspace/shared/reports/ and sent to the QA agent for review.

Requires Docker installed and running. If Docker is unavailable, scans are skipped gracefully.

---

MCP Integration

OCTO VEC supports the Model Context Protocol for extending agent capabilities.

Configure MCP servers in Dashboard > Settings > MCP, or edit mcp-servers.json in your data directory:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_..." }
    }
  }
}

The dashboard includes a directory of 22+ curated MCP servers you can enable with one click.

---

Project Structure

octo-vec/
  src/
    tower.ts              -- Main entry point (startup orchestration)
    config.ts             -- Configuration (env vars + defaults)
    identity.ts           -- Founder profile (from ITS_ME.md)

    atp/                  -- Agent Task Portal (core)
      database.ts         -- SQLite task & employee database
      messageQueue.ts     -- PM message inbox
      agentMessageQueue.ts -- Inter-agent messaging
      eventLog.ts         -- System event audit trail
      agentRuntime.ts     -- Dynamic agent lifecycle
      inboxLoop.ts        -- Background inbox polling
      modelConfig.ts      -- Per-agent model selection
      tokenTracker.ts     -- Cost tracking
      agentGroups.ts      -- Team chat groups
      postTaskHooks.ts    -- Auto security scans

    agents/
      pmAgent.ts          -- Project Manager agent

    ar/                   -- Agent Registry
      roster.ts           -- Roster loader (data/roster.json)
      baseSpecialist.ts   -- Specialist agent base class
      toolProfiles.ts     -- Tool access levels

    memory/
      agentMemory.ts      -- Memory loading (SLTM + LTM)
      sessionLifecycle.ts -- Sunset/sunrise protocol
      autoCompaction.ts   -- Context window management

    tools/
      pm/                 -- PM tools (create task, delegate, start)
      shared/             -- All-agent tools (file I/O, web, messaging)
      domain/             -- Specialist tools (git, security, dev, QA)

    flows/                -- Security scanning pipelines
      semgrepScanFlow.ts, gitleaksScanFlow.ts,
      trivyScanFlow.ts, codeScanFlow.ts

    channels/
      telegram.ts         -- Telegram bot (grammy)
      slack.ts            -- Slack app (Bolt, Socket Mode)
      discord.ts          -- Discord bot (discord.js, Gateway)
      channelManager.ts   -- Channel lifecycle singleton
      channelConfig.ts    -- Credential storage

    dashboard/
      server.ts           -- Express HTTP API + SSE streaming
      security.ts         -- Authentication & rate limiting

    mcp/
      mcpBridge.ts        -- MCP server integration

  dashboard/              -- React frontend (Vite)
    src/views/            -- 10 dashboard views
    src/hooks/            -- useApi, useSSE, usePolling
    src/components/       -- Sidebar, Dropdown, ThemeSwitcher

  core/                   -- Read-only assets (ships with npm)
    prompts/              -- Agent prompt templates
    roster.json           -- Default agent roster seed

  ~/.octo-vec/            -- User data directory (runtime state)
    roster.json           -- Active agent roster
    atp.db                -- SQLite database
    memory/               -- Agent memory files
  workspace/              -- Agent work output (cwd/workspace)
    shared/               -- Cross-agent deliverables
    projects/             -- Standalone projects
    agents/               -- Per-agent workspaces

---

Tech Stack

Layer	Technology
Runtime	Node.js + TypeScript (tsx)
Agent Framework	@mariozechner/pi-agent-core
LLM Providers	22+ via pi-ai (Groq, OpenAI, Anthropic, Google, Mistral, etc.)
Database	SQLite (better-sqlite3)
Dashboard	React + Vite
Real-Time	Server-Sent Events (SSE)
HTTP	Express
Telegram	grammy
Slack	@slack/bolt (Socket Mode)
Discord	discord.js (Gateway WebSocket)
Security Scans	Semgrep, Gitleaks, Trivy, SonarQube (Docker)
MCP	@modelcontextprotocol/sdk

---

CLI Commands

octo-vec start              # Start in daemon mode (dashboard only, no terminal input)
octo-vec start --cli        # Start with full interactive CLI mode
octo-vec start --reset      # Full reset: clear all tasks, memories, queues, histories
octo-vec dashboard          # Re-open the dashboard in your browser
octo-vec migrate            # Migrate old data/ directory to ~/.octo-vec

Development

npm start                   # Start with tsx (dev mode, daemon)
npm start -- --cli          # Start with tsx (dev mode, interactive CLI)
npm run dev                 # Start with hot-reload
npm run dashboard:dev       # Run dashboard frontend in dev mode (HMR)

---

Troubleshooting

Telegram: "409 Conflict"

Another bot instance is polling. Kill the old process and restart. TOWER auto-retries 3 times with 5-second delays.

Slack: Bot started but not responding

• Event Subscriptions > add message.channels (and message.im for DMs)
• OAuth Scopes > add chat:write, channels:history, im:history
• Invite bot to channel: /invite @BotName
• Verify Socket Mode is ON

Discord: Bot offline

• Enable Message Content Intent in Developer Portal > Bot > Privileged Gateway Intents
• Verify bot is invited to server with correct permissions

Agent stuck in "in_progress"

The watchdog marks tasks stuck >5 minutes as failed. You can also manually interrupt:

/interrupt dev "taking too long"

Context window errors

VEC_CONTEXT_WINDOW=128000
VEC_COMPACT_THRESHOLD=0.75
VEC_COMPACT_KEEP_RECENT=20

---

Socials

• Discord — Join the community
• Twitter / X — Follow the octopus
• Instagram — Behind the scenes
• Threads — More tentacles

---

License

MIT

---