Ai Dev Team

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 logs, manifests, patches]

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.

• Token-conscious context packs and lightweight task intelligence for better

Codex/Claude handoffs without replaying full history.

• Workflow gates for review/done/release/deploy readiness based on validation

evidence, open reviews, failed evidence, and deploy dry-runs.

• Local dashboard for projects, task detail, evidence, reviews, worker status,

run manifests, worktrees, and release readiness.

• Lightweight CLI wrapper for setup, doctor, Solo Mode task flow, dashboard,

readiness, prompt audit, MCP registration, Telegram setup, usage/model reports, and development deploy gates.

• Local provider metadata and usage reporting for OpenAI API, Anthropic API,

Codex CLI, and Claude CLI without requiring API 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.

How This Differs

AI Dev Team Cockpit is not trying to replace general AI workspaces or multi-channel personal assistants.

The cockpit can still integrate with channel layers. Treat it as the dev-workflow backend: external adapters may deliver requests, while the cockpit keeps project profiles, task memory, evidence, review findings, and human approval boundaries.

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.

Quick Start

For a fresh checkout, run the setup script from the repository root:

node .\scripts\setup.mjs

If you link or install the package command, the same flow is:

adt init
adt doctor
adt dashboard

adt is the short daily command. The package also keeps the long ai-dev-team command for clarity, scripts, and older docs. adt init is the product-friendly alias for first-run setup.

On macOS/Linux:

node ./scripts/setup.mjs

The setup script:

• checks that Node satisfies the MCP server requirement,
• creates local .ai runtime folders,
• creates .ai/telegram-inbox.local.env from the example if it does not exist,
• installs memory-mcp dependencies when needed,
• builds and tests memory-mcp,
• runs the doctor checks at the end.

It does not overwrite local secrets, Telegram tokens, chat allowlists, target repository paths, or runtime databases.

Check the machine at any time with:

node .\scripts\doctor.mjs

The doctor reads .ai/telegram-inbox.local.env when it exists, so local values such as CODEX_CLI_PATH are used for the Codex CLI check.

Solo Mode CLI

Solo Mode is the shortest path through the cockpit without Telegram, dashboard, or multi-agent setup. It keeps one local task ledger, runs the registered validation command, captures command output plus git diff --stat, and refuses to mark work done until the deterministic gate passes.

adt project register cockpit --path . --validation "cd memory-mcp; npm test"
adt task create "Tighten checkout validation" --project cockpit
adt validate TASK-YYYYMMDD-ABC123
adt gate TASK-YYYYMMDD-ABC123
adt task done TASK-YYYYMMDD-ABC123

For target repositories outside the cockpit, run adt project register from the target folder with --path ., or pass an absolute path. The cockpit memory still lives in this repository's .ai/memory.sqlite.

The done gate is intentionally strict:

• the task must be linked to a registered project,
• the project must have a registered validation_command,
• the latest validation evidence must be passed,
• unresolved failed or blocked evidence must be cleared,
• open review findings must be resolved, accepted, or dismissed.

Useful inspection commands:

adt task list
adt task show TASK-YYYYMMDD-ABC123
adt evidence TASK-YYYYMMDD-ABC123
adt handoff TASK-YYYYMMDD-ABC123
adt status

For a team-facing degraded-state report:

node .\scripts\degraded-report.mjs

Useful setup options:

node .\scripts\setup.mjs --skip-test
node .\scripts\setup.mjs --force-install
node .\scripts\doctor.mjs --json
node .\scripts\degraded-report.mjs --json

For release gate status:

node .\scripts\readiness.mjs
node .\scripts\readiness.mjs --project ai-dev-team
node .\scripts\readiness.mjs --all

After setup, the doctor output prints ready-to-run MCP registration commands for Codex and Claude Code using the absolute paths for the current checkout.

Manual 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 \memory-mcp\dist\server.js --workspace 

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 \memory-mcp\dist\server.js --workspace 

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 | | memory_context_pack_get | Generate a compact builder/reviewer/status/release context pack | | memory_task_intelligence_get | Estimate task difficulty, risk, validation hints, and context budget guidance | | memory_evidence_ledger_get | Generate a reviewer-ready evidence ledger for one task | | memory_workflow_gate_get | Check whether a task is ready for review, done, release, or deploy | | memory_worktree_plan_get | Plan a safe Git worktree for a task role without changing files | | memory_worktree_create | Create a task worktree and record the result as evidence | | memory_validation_suggest | Suggest stack-aware validation commands and evidence to record | | memory_validation_run | Run a trusted validation command and auto-record command output evidence | | memory_git_diff_stat_capture | Capture git diff --stat and record it as evidence | | memory_evidence_artifact_record | Record screenshot, browser console, VS Code problems, run, patch, or deploy artifacts | | memory_prompt_injection_audit | Scan external text for prompt-injection and approval-bypass risk | | memory_deploy_profile_list | List local allowlisted development deploy profiles | | memory_deploy_gate_plan_get | Plan a development deploy gate with dry-run, approval code, and rollback guidance | | memory_publication_safety_check | Check public-release blockers such as secrets, private paths, and missing ignores | | memory_github_issues_sync | Dry-run or apply GitHub issue imports into shared tasks | | memory_release_notes_generate | Generate release notes from shared task memory | | memory_github_pr_summary_get | Summarize a GitHub PR with files, review states, and focus hints | | memory_task_template_list | List reusable task templates | | memory_task_from_template_create | Create a shared task from a reusable template | | memory_scaffold_stack_list | List supported scaffold stacks | | memory_scaffold_plan | Preview stack-specific scaffold files | | memory_scaffold_create | Create a small local scaffold |

Resources:

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

Security Model

Read [THREATMODEL.md](THREATMODEL.md) before exposing the dashboard, connecting new adapters, widening Telegram access, or designing deploy automation. The supported default is local stdio MCP, localhost dashboard, allowlisted Telegram chats, and human-approved merge/push/deploy actions.

Token-Saving Intelligence

The first intelligence layer is deterministic and local. It does not call model APIs or require ML services.

Use memory_context_pack_get when you want a compact prompt-ready handoff for Codex or Claude Code. It can produce builder, reviewer, status, or release packs with a character budget, latest evidence, open findings, relevant project profile, and practical focus notes.

Context packs start with the highest-signal state: workflow gate result, next action, latest important evidence, and open review count. This helps agents avoid replaying full task history when the current quality state is enough.

Use memory_task_intelligence_get to estimate:

• task difficulty and risk,
• whether reviewer handoff is recommended,
• likely validation commands,
• next steps and open questions,
• context budget guidance for saving tokens.

These tools are intentionally modest. They improve output quality by giving agents the right context sooner, while keeping the local-first setup simple.

Dev-Team Core

The v0.2 direction starts with repo-safe collaboration primitives rather than a general AI chat surface.

Use memory_evidence_ledger_get to generate a reviewer-ready task audit. It summarizes the task, project profile, evidence records, validation status, open review findings, decisions, timeline, and a practical reviewer checklist.

Use memory_workflow_gate_get before moving a task to review, done, release, or deploy. The gate fails when validation is missing for done/release/deploy, failed evidence is still present, open reviews are unresolved, or deploy dry-run evidence is missing for deploy approval.

Use memory_evidence_artifact_record for optional but high-value artifacts: screenshot files, browser console exports, VS Code Problems exports, run manifests, patch files, deploy gate outputs, or any other durable artifact path.

Use memory_worktree_plan_get before non-trivial work to get a safe worktree plan for a builder, reviewer, or validation role. The plan includes branch, path, create command, inspect command, cleanup command, warnings, and safety notes.

Use memory_worktree_create when you want the MCP server to create the Git worktree and record the result as task evidence. It only operates on a task linked to a registered project, defaults to refusing a dirty base repository, and never pushes, merges, resets, deletes, deploys, or discards changes.

Recommended flow for bigger tasks:

1. Register the target repository.
2. Create a task linked to that project.
3. Plan or create a builder worktree.
4. Run implementation and validation in the worktree.
5. Record validation and diff evidence.
6. Generate the evidence ledger for Claude Code or another reviewer.
7. Merge, push, or deploy only after human approval.

Smart Validation And Templates

memory_validation_suggest inspects registered project metadata, known task context, optional changed files, and lightweight local project signals such as package.json, tsconfig.json, composer.json, or Laravel artisan. It then suggests validation commands and evidence fields to record. Registered validation_command values remain the first source of truth.

memory_validation_run closes the loop by running a trusted validation command from the registered project profile or runnable suggestions, capturing terminal output, optionally adding git diff --stat, and recording the result through the normal evidence table. memory_git_diff_stat_capture records only the diff stat when you want lightweight review context without rerunning tests.

Task templates provide repeatable starti

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: JoeSoep
• Source: JoeSoep/ai-dev-team
• License: MIT

Install and usage instructions live in the source repository linked above.