OCTO VEC

Your AI Team, Not Just Another AI Tool

A virtual software company — 9 autonomous AI agents that collaborate like real employees. You talk to the PM. They handle the rest. No meetings. Just tentacles.

Landing Page · Discord · Twitter · LinkedIn

Watch the Demo

9 AI agents communicating in real-time — PM at center, specialists in orbit

What is OCTO VEC?

OCTO VEC is an open-source virtual software company — 9 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, and Tech Writer.

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

Your default roster — 9 agents ready to work:

| Agent | Name | Role | What They Do | |:---:|---|---|---| | PM | Arjun Sharma | Project Manager | The octopus in charge. Breaks down tasks, assigns work, keeps everyone on track | | Architect | Priya Nair | Solutions Architect | System design, database schemas, API contracts, tech stack decisions | | BA | Kavya Nair | Business Analyst | Turns vague requests into crystal-clear requirements and user stories | | Researcher | Shreya Joshi | Research Specialist | Technology research, best practices, benchmarks, comparison reports | | Developer | Rohan Mehta | Senior Developer | Writes production code (Python, JS, TS), runs tests, fixes bugs | | QA | Preethi Raj | QA Engineer | Test plans, test cases, reviews scan reports, validates deliverables | | Security | Vikram Singh | Security Engineer | Vulnerability scans, code audits, OWASP compliance | | DevOps | Aditya Kumar | DevOps Engineer | CI/CD pipelines, Dockerfiles, Kubernetes, deployment configs | | Tech Writer | Anjali Patel | Technical Writer | API docs, READMEs, user guides, architecture decision records |

15 more agents available — enable from the Dashboard > Directory view:

Frontend Developer, Backend Developer, Mobile Developer, Data Engineer, DBA, ML Engineer, SRE, Product Owner, UI/UX Designer, Scrum Master, Data Analyst, Release Manager, Compliance Officer, Support Engineer.

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)

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

Communication

• 4 Channels — CLI, Telegram, Slack, Discord — 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 (9+ 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 + Telegram + Slack + Discord) | — | — | Slack | Slack | — | — | Yes (4) | | Real-time web dashboard | — | — | Yes | Yes | — | — | Yes (10 views) | | Self-hosted, vendor-agnostic | — | — | — | Yes | Yes | Yes | Yes | | MCP support | Yes | Yes | Yes | Yes | — | — | Yes | | Per-agent cost tracking | — | — | — | — | — | — | 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

Prerequisites

• Node.js 18+
• An LLM API key (Groq free tier works great to start)
• Docker (optional — for security scanning)

Install from npm

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 channels support the same commands and route messages to the same PM agent.

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
• LinkedIn — Professional tentacles
• Instagram — Behind the scenes
• Threads — More tentacles

License

MIT

Built by Akhil — One human, one octopus, zero meetings.

Finally, a company where nobody takes sick leave, nobody argues in Slack, and code actually gets shipped.