octo-vec 1.0.0

package/README.md

@@ -0,0 +1,646 @@
+<div align="center">
+
+# 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.
+
+[![Open Source](https://img.shields.io/badge/status-open%20source-3fb950?style=for-the-badge)](https://github.com/akhil2129/octo-vec)
+[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![SQLite](https://img.shields.io/badge/SQLite-003B57?style=for-the-badge&logo=sqlite&logoColor=white)](https://www.sqlite.org/)
+[![Docker](https://img.shields.io/badge/Docker-2496ED?style=for-the-badge&logo=docker&logoColor=white)](https://www.docker.com/)
+
+[Landing Page](https://octovec.ai) · [Discord](https://discord.gg/spdRmufS) · [Twitter](https://x.com/OctoVec_ai) · [LinkedIn](https://www.linkedin.com/in/octo-vec-9883073b4/)
+
+<br/>
+
+<a href="https://www.youtube.com/watch?v=6UJH4bcs-hM">
+  <img src="https://img.youtube.com/vi/6UJH4bcs-hM/maxresdefault.jpg" alt="OCTO VEC Demo" width="700"/>
+</a>
+
+**[Watch the Demo](https://www.youtube.com/watch?v=6UJH4bcs-hM)**
+
+<br/>
+
+<img src="landing/neural-network.gif" alt="OCTO VEC Neural Agent Network" width="500"/>
+
+*9 AI agents communicating in real-time — PM at center, specialists in orbit*
+
+</div>
+
+---
+
+## 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
+
+```bash
+npm install -g octo-vec
+octo-vec start
+```
+
+### Or run from source
+
+```bash
+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](https://t.me/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`:
+   ```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](https://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`:
+   ```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](https://discord.com/developers/applications) > 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`:
+   ```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**:
+
+```env
+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
+
+```env
+# 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](https://modelcontextprotocol.io/) for extending agent capabilities.
+
+Configure MCP servers in **Dashboard > Settings > MCP**, or edit `mcp-servers.json` in your data directory:
+
+```json
+{
+  "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](https://github.com/nicholasgasior/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
+
+```bash
+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
+
+```bash
+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
+```env
+VEC_CONTEXT_WINDOW=128000
+VEC_COMPACT_THRESHOLD=0.75
+VEC_COMPACT_KEEP_RECENT=20
+```
+
+---
+
+## Socials
+
+- [Discord](https://discord.gg/spdRmufS) — Join the community
+- [Twitter / X](https://x.com/OctoVec_ai) — Follow the octopus
+- [LinkedIn](https://www.linkedin.com/in/octo-vec-9883073b4/) — Professional tentacles
+- [Instagram](https://www.instagram.com/octovec.ai/) — Behind the scenes
+- [Threads](https://www.threads.com/@octovec.ai) — More tentacles
+
+---
+
+## License
+
+MIT
+
+---
+
+<div align="center">
+
+**Built by [Akhil](https://github.com/akhil2129) — One human, one octopus, zero meetings.**
+
+*Finally, a company where nobody takes sick leave, nobody argues in Slack, and code actually gets shipped.*
+
+</div>