AI Dev Team Cockpit

Local-first cockpit for coordinating Codex, Claude Code, shared task memory, and optional Telegram-triggered work. The project is designed to run on a developer machine without requiring a hosted orchestrator or model API keys.

Architecture

flowchart LR
  Human[Maintainer] --> IDE[VS Code or terminal]
  IDE --> Codex[Codex builder]
  IDE --> Claude[Claude Code reviewer]

  Codex --> MCP[memory-mcp server]
  Claude --> MCP
  MCP --> SQLite[(local SQLite)]
  MCP --> Docs[.ai project docs]

  Telegram[Telegram bot] --> Inbox[Markdown inbox]
  Inbox --> Worker[Codex inbox worker]
  Worker --> CodexExec[codex exec]
  CodexExec --> Target[allowlisted target repo]
  CodexExec --> Runs[local run logs]

Loading

What This Provides

• A Node/TypeScript MCP server backed by local SQLite.
• Shared project registry, tasks, progress, decisions, evidence, and review findings for builder/reviewer workflows.
• Git-tracked project context in .ai/PROJECT.md and .ai/DECISIONS.md.
• Optional Telegram inbox that writes allowlisted messages into local Markdown task files.
• Optional Codex inbox worker that runs codex exec for explicit allowlisted project keys.
• GitHub-ready public release materials, including roadmap issue drafts and release notes.

Runtime databases, Telegram tokens, chat IDs, target repository paths, and run logs are intentionally local and ignored by Git.

Status

This is an early local-first MVP for individual developers and small teams. It is useful for shared task memory, evidence capture, reviewer handoff, Telegram inbox capture, and explicit local Codex automation.

It is not a hosted SaaS orchestrator, multi-tenant queue, production deployment system, or unattended infrastructure automation platform. Keep a human review step before merging, deploying, running production migrations, or changing secrets.

Requirements

• Node.js version compatible with memory-mcp/package.json.
• npm.
• Codex CLI if you want Codex automation.
• Claude Code if you want Claude reviewer handoff.
• A Telegram bot token only if you enable Telegram inbox mode.

Target applications can use any stack. Register each target repository with its own path, runtime notes, and validation command instead of relying on global language commands.

Install

From the repository root:

cd .\memory-mcp
npm install
npm run build
npm test

The MCP runtime database is created at .ai/memory.sqlite. It is ignored by Git.

Add The MCP Server To Codex

Build first, then register the compiled server. Use absolute paths for your machine.

codex mcp add ai-dev-memory -- node <absolute-path-to-repo>\memory-mcp\dist\server.js --workspace <absolute-path-to-repo>

On macOS/Linux:

codex mcp add ai-dev-memory -- node /path/to/ai-dev-team/memory-mcp/dist/server.js --workspace /path/to/ai-dev-team

Reload your Codex session after adding the server.

Add The MCP Server To Claude Code

User scope is recommended so Claude can read the same memory while reviewing a different target repository.

claude mcp add --scope user ai-dev-memory -- node <absolute-path-to-repo>\memory-mcp\dist\server.js --workspace <absolute-path-to-repo>

On macOS/Linux:

claude mcp add --scope user ai-dev-memory -- node /path/to/ai-dev-team/memory-mcp/dist/server.js --workspace /path/to/ai-dev-team

MCP Tools

Tool	Purpose
memory_project_register	Register or update a target repository profile
memory_project_list	List registered repositories
memory_project_get	Read one repository profile and recent tasks
memory_task_create	Create a shared task
memory_task_list	List shared tasks
memory_task_get	Read a task bundle
memory_task_update	Update task status, assignee, or next action
memory_progress_append	Record agent progress
memory_decision_record	Record a decision and rationale
memory_evidence_record	Record validation output or artifact evidence
memory_review_record	Record reviewer findings
memory_handoff_get	Generate a readable handoff

Resources:

• memory://project/context reads .ai/PROJECT.md.
• memory://project/decisions reads .ai/DECISIONS.md.

Register A Target Repository

Before creating application tasks, register the target repository with memory_project_register. This is where project-specific infrastructure belongs: paths, stack, validation command, and runtime notes.

Example:

project_id: app
name: Example App
path: C:\path\to\app
stack: Laravel/PHP
php_executable: C:\tools\php82\php.exe
validation_command: C:\tools\php82\php.exe artisan test
notes: Use the PHP binary bundled for this app, not the global php command.

Use Linux/macOS paths and commands when those match your environment.

Optional PHP Helper

scripts/php82.ps1 is a convenience wrapper for Windows users who frequently work across different PHP installations. It resolves PHP in this order:

1. AI_DEV_TEAM_PHP
2. PHP82_PATH
3. PHP_PATH
4. php from PATH

Example:

$env:AI_DEV_TEAM_PHP = "C:\tools\php82\php.exe"
.\scripts\php82.ps1 -v

For non-PHP projects, ignore this helper.

Telegram Inbox

Telegram inbox mode captures allowlisted Telegram messages as Markdown files in .ai/inbox/telegram. It does not run commands by itself.

Flow:

Telegram
 -> scripts/telegram-inbox.mjs
 -> .ai/inbox/telegram/*.md
 -> Codex or the local inbox worker processes the task

Setup:

1. Create a bot with @BotFather and get the bot token.
2. Copy the example env file:

Copy-Item .ai\telegram-inbox.local.env.example .ai\telegram-inbox.local.env

3. Fill TELEGRAM_BOT_TOKEN.
4. Start discovery mode with TELEGRAM_ALLOWED_CHAT_IDS empty.
5. Send /start to the bot.
6. Copy the returned chat ID into TELEGRAM_ALLOWED_CHAT_IDS.
7. Restart the inbox script.

Run:

node .\scripts\telegram-inbox.mjs

Example messages:

/task app: add validation for the checkout flow
docs: update onboarding instructions

Codex Inbox Worker

The worker is optional. It watches Telegram inbox files and starts a new codex exec process for each task. It only works for project keys listed in CODEX_WORKER_PROJECTS.

Configure .ai/telegram-inbox.local.env:

CODEX_WORKER_PROJECTS=app=C:\path\to\app;cockpit=C:\path\to\ai-dev-team
CODEX_WORKER_DEFAULT_PROJECT=app
CODEX_COMMAND=codex
# CODEX_CLI_PATH=C:\path\to\codex.exe
CODEX_SANDBOX_MODE=workspace-write
CODEX_APPROVAL_POLICY=never
TELEGRAM_NOTIFY_RESULTS=true

On macOS/Linux:

CODEX_WORKER_PROJECTS=app=/home/me/projects/app;cockpit=/home/me/projects/ai-dev-team

Run the inbox and worker in separate terminals:

node .\scripts\telegram-inbox.mjs
node .\scripts\codex-inbox-worker.mjs

Automatic flow:

Telegram /task app: add validation
 -> .ai/inbox/telegram/*.md
 -> Codex Inbox Worker
 -> codex exec -C <allowlisted-project-path>
 -> inbox file moves to done or failed
 -> optional Telegram summary is sent back to the source chat
 -> logs are written to .ai/runs/telegram-codex

Worker safety boundaries:

• Only project keys in CODEX_WORKER_PROJECTS are executable.
• The default sandbox is workspace-write.
• The worker prompt forbids push, deploy, production migrations, data deletion, and secret changes.
• Review the diff from your normal development environment before merging or deploying.

VS Code Tasks

The repository includes tasks for common local actions:

• Memory MCP: Build
• Memory MCP: Test
• PHP Runtime: Version
• Telegram Inbox: Start
• Codex Inbox Worker: Start

These tasks use the current workspace folder and local env files, so they can be used from different checkout paths.

Publishing

Suggested GitHub metadata is tracked in .github/settings.yml. Roadmap issue drafts live in .github/roadmap-issues, and the first release notes live in .github/releases/v0.1.0.md.

If you have a GitHub token with repository permissions, you can publish the metadata, roadmap issues, and v0.1.0 release with:

$env:GITHUB_TOKEN = "<token>"
$env:GITHUB_REPOSITORY = "owner/repo"
node .\scripts\github-publish-v0.1.0.mjs

License

MIT. See LICENSE.