tandem-browser: Instructions file for Codex

AGENTS.md — Tandem Browser Development Guide

Internal development workflow document. This file exists for local developer and coding-agent operations and is not the primary public project guide.

Who Are You?

You are a developer agent working on Tandem Browser: an Electron browser built for human-AI symbiosis. The user (the human) and Wingman (the AI) browse the web together. You write the code.

Read PROJECT.md first. It contains the full overview of what Tandem is, how it works, and why it exists. Read ARCHITECTURE.md before changing code — it explains the layer model, the manager system, and where everything lives.

The Project

• Repo: hydro13/tandem-browser (GitHub: hydro13)
• Stack: Electron + TypeScript + Express.js API (localhost:8765) + MCP server with 257 tools (count maintained by scripts/check-consistency.js)
• Goal: An agent-first browser where any AI (via MCP, HTTP API, or WebSocket) and a human browse together
• Philosophy: Local-first, privacy-first, no cloud dependencies in the browser itself
• Tests: Vitest; unit tests live in src/**/tests/
• Versioning: See package.json and CHANGELOG.md for the current release and full history

Counts in docs: trust only the automated ones. The MCP tool count and the version number are enforced across docs by scripts/check-consistency.js (part of npm run verify) — those you can trust. Any other count you find in documentation (managers, files, modules) may have drifted; the authoritative sources are src/registry.ts for the manager list, src/mcp/tools/ for the MCP tool surface, and src/api/routes/ for the HTTP API surface. When a doc and the code disagree, the code is right — fix the doc while you are there.

Project Structure

tandem-browser/
├── src/                       # TypeScript application code (main process)
│   ├── main.ts                # Electron main process entry
│   ├── registry.ts            # ManagerRegistry — source of truth for managers
│   ├── bootstrap/             # Manager instantiation and wiring
│   ├── api/                   # Express API server; routes in api/routes/
│   ├── mcp/                   # MCP server; tools in mcp/tools/ (one file per domain)
│   ├── security/              # 8-layer shield (see ARCHITECTURE.md)
│   ├── extensions/            # Browser extension system
│   ├── snapshot/              # Accessibility tree with @refs
│   ├── platform/              # Platform adapters (macOS baseline, Windows track)
│   └── <domain>/              # ~50 single-responsibility domains, one dir each
├── shell/                     # Browser UI (Electron renderer)
├── cli/                       # tandem CLI (@hydro13/tandem-cli)
├── docs/                      # Public site + project documentation
│   ├── implementations/       # Completed implementation plans
│   ├── plans/                 # Not-yet-implemented design docs
│   ├── templates/             # design-template.md, manager-pattern.md
│   ├── research/              # Analyses and feature inventories
│   └── archive/               # Historical documents
├── scripts/                   # Build, launch, and consistency scripts
├── skill/                     # Agent skill file (SKILL.md)
├── tests/                     # Smoke tests (unit tests live in src/**/tests/)
├── ARCHITECTURE.md            # System structure — read before changing code
├── PROJECT.md                 # Product vision
├── AGENTS.md                  # This file
├── TODO.md                    # Current priorities
└── CHANGELOG.md