Content
# Tool List
Portable MCP + Skills + Rules package for AI coding environments.
This project started as an Antigravity-only internal MCP stack and has now been reorganized into a shared toolkit for **Antigravity / Codex / Claude Code (CC) / Windsurf (WSF) with cross-host data interoperability**. The goal is to let different AI hosts share the same local capabilities, the same memory/Record data, and similar working habits.
The current public snapshot now contains **MCP + Skills + Rules**. `skills/` contains portable user-side Codex skills; it excludes `.system` bundled skills, plugin cache, runtime caches, and private data.
> 2026-07-04 refresh: latest MCP sources and rules templates are refreshed and privacy-scrubbed; `memory-store` is now `1.17.1`, `sandbox` is `1.13.7`, `web-fetcher` remains `7.0.0`, `mcp-subagent` remains Windsurf-only optional, and `broker` keeps portable path/data-root patches plus upstream request timeout handling.
## Core Features
### Cross-host Data Interoperability
- Supports Antigravity, Codex, Claude Code (CC), and Windsurf (WSF).
- Exposes the same MCP endpoints through a shared HTTP broker.
- Uses a shared data root so memory, Records, conversation reading, and Stage Guard can work across hosts.
- Supports `chain`, `dataChain`, and `modelChain` to split default routing, conversation data source, and model-call route.
Common examples:
- `dataChain="claude-code"`: read Claude Code local conversation data.
- `dataChain="windsurf"`: read Windsurf / Cascade local conversation data; this package does not expose `modelChain="windsurf"`.
- `dataChain="codex"`: read Codex local thread / JSONL / SQLite index data.
- `dataChain="antigravity"`: read Antigravity Language Server conversation data.
- `modelChain="codex"`: use the Codex model bridge.
- `modelChain="antigravity"`: use the Antigravity model route.
- `modelChain="claude-code"`: explicitly use Claude Code CLI; hidden automatic CC quota usage is intentionally avoided by default.
### MCP: Local Capability Layer
The current implementation includes three shared core MCPs, one HTTP broker, and one Windsurf-exclusive optional MCP:
| MCP | Current Version | Key Capabilities |
| --- | --- | --- |
| `memory-store` | `1.17.1` | Memory, conversation reading, Record, Golden Extract, Stage Guard, cross-host data chain, query parsing/scoring, Windsurf Cascade routing and local fallback |
| `web-fetcher` | `7.0.0` | Headless browsing, web scraping, screenshot, interaction, login state, file reading/conversion, multi-format visual inspection |
| `sandbox` | `1.13.7` | Code execution, persistent REPL, batch tasks, long task hosting, smart search, Codex/CC invocation, multi-model council, SSRF/injection hardening, background abort and per-task registry |
| `broker` | `0.1.0` | Exposes stdio MCP as streamable HTTP for reuse by Codex / Claude Code / Windsurf |
| `mcp-subagent` | `0.0.1` | Windsurf-exclusive async subagent: spawn / poll / reply / collect / interrupt / dispose; not enabled by default as a shared MCP across hosts |
`mcp-subagent` requires special handling: it operates on real Cascade conversations through Windsurf / Devin Language Server and is a Windsurf-private automation capability. Its source code is located in `mcps/mcp-subagent/`, but the default installation script does not automatically write it to the global broker or Windsurf configuration; it requires explicit authorization from the recipient and execution according to `mcps/mcp-subagent/README.md` for dry-run, backup, apply, and rollback.
#### memory-store: Conversation / Record / Guard Hub
`memory-store` is the long-term memory and conversation data core of this toolkit.
Key capabilities:
- `memory_query` / `memory_write` / `memory_update` / `memory_batch`: cross-workspace memory read/write, query, and maintenance.
- `conversation_read_original`: read original conversations from Antigravity / Codex / Claude Code / Windsurf by ID, title, or keyword.
- `conversation_golden_extract`: extract high-value segments from long conversations.
- `record_manage`: generate and maintain structured Records, converting long conversations into stages, outputs, risks, validations, and experiences.
- `stage_guard`: perform gate checks by `Task.md` stages, supporting external evidence indexing, and preventing omission, premature completion, insufficient evidence, and Guard self-reference loops.
- Explicit `conversationId` / `ownerId`: enhance stability in cross-host, cross-conversation, background task, and shared broker scenarios.
- Query parsing, relevance scoring, Windsurf Cascade multi-window routing, and local `.pb` fallback: improve cross-source conversation location and reading reliability.
#### web-fetcher: Web, Browser, and Local File Understanding
`web-fetcher` is the entry point for web and visual inspection.
Key capabilities:
- Headless browsing based on Playwright / Chromium, suitable for full-page scraping, screenshot, page interaction, and automated inspection.
- Supports web tools like `web_fetch_page`, `web_fetch_rich`, `web_fetch_screenshot`, `web_interact`, and `web_pipeline`.
- Supports login state, Cookie/localStorage backup, session reuse, and owner isolation.
- Supports local file and multi-format content inspection: HTML, PDF, PPTX, EPUB, Office conversion paths, etc., with specific capabilities depending on local dependencies.
- Supports `web_inspect` for overlap, overflow, readability, screenshot, and AI visual review, suitable for PPT / report / web UI QA.
- `ai_summary` / `ai_review` supports `modelChain`, allowing model route selection between Antigravity, Codex, and Claude Code.
#### sandbox: Execution, Search, and Multi-model Council
`sandbox` is the isolated execution and multi-model collaboration layer.
Key capabilities:
- `sandbox_exec`: execute short code or commands, supporting Python / Node / PowerShell / cmd / bash, with code/command mutex checking and regression.
- `sandbox_session`: persistent REPL sessions.
- `sandbox_batch`: batch parallel task execution.
- `sandbox_launch`: long task decoupling execution, log and status persistence; per-task registry, cwd validation, spawn error persistence, and background abort cleanup for improved stability.
- `smart_search`: intelligent search in large directories / long files, with `rg` detection changed to shellless to reduce injection and ESM compatibility risks.
- `sandbox_codex`: invoke Codex CLI for background tasks.
- `sandbox_council`: multi-model review, supporting routes like Antigravity, Codex, Claude Code, Gemini CLI, OpenAI/Anthropic/Gemini/custom provider, etc.
- Council supports large input chunking, complex file indexing, Gemini CLI / Codex CLI fallback, stress input timeout, and participant/host partitioning.
### Skills: Portable Workflow Layer
The repository currently contains a `skills/` directory with portable user-side Codex skills copied from `%USERPROFILE%/.codex/skills`.
Current Skills:
- Document skills: the current public package includes `pdf`; `docx` / `pptx` / `xlsx` are not redistributed with GitHub packages due to local license restrictions, and recipients should install authorized versions themselves.
- Design skills: front-end design, canvas design, theme factory, etc.
- Tool construction skills: MCP construction, Skill creation, Playwright / browser testing, etc.
- Packaging boundary: does not include `.system/`, plugin cache, `node_modules`, `dist`, `__pycache__`, generated test output, logs, cookies, sessions, auth files, or local private data. Office skills (`docx` / `pptx` / `xlsx`) are excluded due to license restrictions.
### Rules: Making AI a Better Long-term Collaborator
The current Rules are a "digital cat girl / friend-like collaboration" version. The core goal is not role-playing itself but making AI **speak human language, be less pseudo-human**, and have less template tone, report tone, and mechanical endings, with more natural feedback, boundary awareness, evidence awareness, and task closure capabilities.
Rules cover four hosts:
- Codex: `rules/codex/AGENTS.template.md`
- Codex optional system prompt: `rules/codex/system-prompt.template.md`
- Antigravity: `rules/antigravity/GEMINI.template.md`
- Claude Code (CC): `rules/claude-code/CLAUDE.template.md`
- Windsurf (WSF): `rules/windsurf/Windsurf_Global_Rules.template.md`
Main constraints of Rules:
- Prioritize Chinese and natural spoken language, reducing template and pseudo-human elements.
- Distinguish between chat mode and task mode.
- Use subagents / council more actively but with boundaries.
- For complex tasks, read memory and context first, and update Records if necessary.
- Perform visual and structural QA on products like PPT, documents, web pages, and UI.
- For high-risk operations, clarify impacts, backup and rollback paths first.
- Make explicit constraints on the usage sequence and degradation path of Exa, web-fetcher, sandbox, and memory-store.
## Included Content
| Module | Path | Description |
| --- | --- | --- |
| MCP servers | `mcps/` | `memory-store`, `web-fetcher`, `sandbox`, portable HTTP broker, and Windsurf-exclusive `mcp-subagent` |
| Rules templates | `rules/` | Four independent templates for Codex, Antigravity, Claude Code, and Windsurf |
| Installation scripts | `install/` | Windows PowerShell build, configuration, broker start/stop, and smoke test scripts |
| Configuration templates | `templates/` | Examples for Codex, Antigravity, Claude Code, Windsurf, and environment variables |
| Skills | `skills/` | Portable user-side Codex skills, README, and manifest |
| Test cases | `design-tests/` | Local test pages and MCP HTTP smoke test auxiliary files |
## Quick Start on Windows
Environment requirements:
- Node.js 18+
- npm
- PowerShell
- Install Codex, Antigravity, Claude Code, or Windsurf as needed
Build and test:
```powershell
./install/Install-CodexToolkit.ps1
./install/Start-CodexMcpBroker.ps1
./install/Test-CodexToolkit.ps1
./install/Stop-CodexMcpBroker.ps1
```
To build Windsurf-exclusive `mcp-subagent` source code, run `./install/Install-CodexToolkit.ps1 -IncludeWindsurfSubagent`; this switch only builds the source code and does not automatically write it to Windsurf or broker configurations.
The broker exposes the following local endpoints by default:
```text
http://127.0.0.1:14588/memory-store/mcp
http://127.0.0.1:14588/web-fetcher/mcp
http://127.0.0.1:14588/sandbox/mcp
http://127.0.0.1:14588/exa/mcp # Optional, requires Exa URL configuration by the recipient
```
## Privacy Boundary
This repository should only contain source code, templates, documentation, and test cases.
Do not submit:
- API Keys or remote MCP URLs with keys
- Cookies, browser profiles, auth files, sessions, logs
- Real memory-store data or Record files
- SQLite databases or JSONL conversation history
- Local absolute paths
- Personal account links or identifiable information
Before release, run:
```powershell
$env:CODEX_TOOLKIT_PRIVATE_PATTERNS="<your_private_patterns_separated_by_semicolons>"
./install/Test-CodexToolkit.ps1 -PackageClean
```
## Repository Structure
```text
.
├─ mcps/
│ ├─ broker/
│ ├─ memory-store/
│ ├─ mcp-subagent/
│ ├─ sandbox/
│ └─ web-fetcher/
├─ rules/
│ ├─ codex/
│ ├─ antigravity/
│ └─ claude-code/
├─ install/
├─ skills/
├─ templates/
├─ design-tests/
├─ PACKAGE_MANIFEST.md
├─ PRIVATE_EXCLUDE_CHECKLIST.md
├─ TOOLKIT_README.md
└─ SETUP.md
```
## License
MIT. See `LICENSE`.
---
### MCP: Local Capability Layer
| MCP | Version | Main Capabilities |
| --- | --- | --- |
| `memory-store` | `1.17.1` | Memory, conversation reading, Conversation Export, Records, Golden Extract, Stage Guard, four-source data chains, query parsing / relevance scoring, WSF Cascade routing, and local fallback |
| `web-fetcher` | `7.0.0` | Headless browsing, web fetch, screenshots, interactions, login state, local file / multi-format inspection |
| `sandbox` | `1.13.7` | Code execution, persistent REPL, batch jobs, long-running tasks, smart search, Codex/CC calls, multi-model council, SSRF/injection fixes, background abort, and per-task registry |
| `broker` | `0.1.0` | Exposes stdio MCP servers as Streamable HTTP endpoints for Codex / Claude Code / Windsurf and other hosts |
| `mcp-subagent` | `0.0.1` | Windsurf-only async sub-agents: spawn / poll / reply / collect / interrupt / dispose; not enabled as a default shared MCP |
`mcp-subagent` is special: it operates real Windsurf / Devin Cascade conversations through the local Language Server. The source is included under `mcps/mcp-subagent/`, but the default installer does not automatically patch the shared broker or Windsurf config. Receivers should follow `mcps/mcp-subagent/README.md` and run dry-run, backup, apply, and rollback steps only with explicit local authorization.
#### memory-store: Conversation / Record / Guard Hub
`memory-store` is the long-term memory and conversation-data core.
Highlights:
- `memory_query` / `memory_write` / `memory_update` / `memory_batch`: workspace-aware memory operations.
- `conversation_read_original`: read original conversations by ID, title, or keyword across Antigravity / Codex / Claude Code / Windsurf.
- `conversation_golden_extract`: extract high-value snippets from long conversations.
- `record_manage`: generate and maintain structured Records with phases, outputs, risks, verification, and lessons.
- `stage_guard`: stage-level guardrails for `Task.md` workflows with external evidence indexing, preventing missing work, premature completion reports, weak evidence, and self-referential guard loops.
- Explicit `conversationId` / `ownerId`: stabilizes cross-host, cross-conversation, background-task, and shared-broker usage.
- Query parsing, relevance scoring, Windsurf Cascade multi-window routing, and local `.pb` fallback improve cross-source conversation lookup and reads.
#### web-fetcher: Web, Browser, and Local File Understanding
Highlights:
- Playwright / Chromium based headless browsing for web fetch, screenshots, page interactions, and automated checks.
- Tools such as `web_fetch_page`, `web_fetch_rich`, `web_fetch_screenshot`, `web_interact`, and `web_pipeline`.
- Login state, Cookie/localStorage backup, session reuse, and owner isolation.
- Local file and multi-format inspection support: HTML, PDF, PPTX, EPUB, and Office conversion paths where local dependencies are available.
- `web_inspect` for overlap, overflow, readability, screenshot, and AI visual review, useful for PPT / reports / web UI QA.
- `ai_summary` / `ai_review` with `modelChain` support across Antigravity, Codex, and Claude Code; Windsurf is currently data-chain oriented.
#### sandbox: Execution, Search, and Multi-Model Council
Highlights:
- `sandbox_exec`: run short code or commands, including Python / Node / PowerShell / cmd / bash, with code/command mutex regression coverage.
- `sandbox_session`: persistent REPL sessions.
- `sandbox_batch`: parallel batch execution.
- `sandbox_launch`: detached long-running tasks with logs and status on disk; per-task registry, cwd validation, spawn-error persistence, and background abort cleanup are improved.
- `smart_search`: smart search over large directories or long files; `rg` probing is shellless for safer ESM/runtime behavior.
- `sandbox_codex`: background tasks through Codex CLI.
- `sandbox_council`: multi-model council with Antigravity, Codex, Claude Code, Gemini CLI, OpenAI/Anthropic/Gemini/custom providers.
- Council support for large-input chunking, complex-file indexing, Gemini CLI / Codex CLI fallback, pressure timeouts, and moderator/participant separation.
### Skills: Portable Workflow Layer
This repository now includes a `skills/` directory copied from portable user-side `%USERPROFILE%/.codex/skills` entries.
Planned Skill directions:
- Document workflows: this public package includes `pdf`; `docx` / `pptx` / `xlsx` are excluded from GitHub redistribution because their local licenses restrict copying, so receivers should install licensed equivalents themselves.
- Design workflows: frontend design, canvas design, theme factory.
- Tool-building workflows: MCP builder, skill creator, Playwright / browser testing.
- Packaging boundary: excludes `.system/`, plugin cache, `node_modules`, `dist`, `__pycache__`, generated test outputs, logs, cookies, sessions, auth files, and local private data. Office skills (`docx` / `pptx` / `xlsx`) are excluded due to redistribution restrictions.
### Rules: Making AI a Better Long-Term Collaborator
The current Rules are a catgirl / friendly-collaborator variant. The point is not roleplay for its own sake; the practical goal is to make AI agents **sound more human and less uncanny or template-like**, while preserving directness, evidence discipline, boundary awareness, and useful progress updates.
Rules cover:
- Codex: `rules/codex/AGENTS.template.md`
- Optional Codex system prompt: `rules/codex/system-prompt.template.md`
- Antigravity: `rules/antigravity/GEMINI.template.md`
- Claude Code (CC): `rules/claude-code/CLAUDE.template.md`
- Windsurf (WSF): `rules/windsurf/Windsurf_Global_Rules.template.md`
Rules mainly define:
- Natural conversation style with fewer template-like reports.
- Chat mode vs task mode distinction.
- Proactive but bounded subagent / council usage.
- Memory and context lookup before complex work, with Record updates when useful.
- Visual and structural QA for PPT, documents, webpages, and UI artifacts.
- High-risk operation boundaries: explain impact, backup, and rollback first.
- Clear tool usage and fallback rules for Exa, web-fetcher, sandbox, and memory-store.
## Included
| Area | Path | Notes |
| --- | --- | --- |
| MCP servers | `mcps/` | `memory-store`, `web-fetcher`, `sandbox`, a portable HTTP broker, and WSF-only `mcp-subagent` |
| Host rules | `rules/` | Separate templates for Codex, Antigravity, Claude Code, and Windsurf |
| Install scripts | `install/` | Windows PowerShell scripts for build, config, broker lifecycle, and smoke tests |
| Config templates | `templates/` | Codex, Antigravity, Claude Code, Windsurf, and environment examples |
| Skills | `skills/` | Portable user-side Codex skills, README, and manifest |
| Smoke tests | `design-tests/` | Local pages and MCP HTTP smoke test helpers |
## Quick Start On Windows
Requirements:
- Node.js 18+
- npm
- PowerShell
- Codex, Antigravity, Claude Code, or Windsurf depending on your target host
Build and smoke test:
```powershell
./install/Install-CodexToolkit.ps1
./install/Start-CodexMcpBroker.ps1
./install/Test-CodexToolkit.ps1
./install/Stop-CodexMcpBroker.ps1
```
To also build the Windsurf-only `mcp-subagent` source, run `./install/Install-CodexToolkit.ps1 -IncludeWindsurfSubagent`; it only builds source and does not auto-patch Windsurf or broker config.
Default broker endpoints:
```text
http://127.0.0.1:14588/memory-store/mcp
http://127.0.0.1:14588/web-fetcher/mcp
http://127.0.0.1:14588/sandbox/mcp
http://127.0.0.1:14588/exa/mcp # optional, requires receiver-side Exa URL
```
## Privacy Boundary
This repository should only contain source code, templates, docs, and test samples.
Do not commit:
- API keys or remote MCP URLs with embedded keys
- cookies, browser profiles, auth files, sessions, or logs
- real memory-store data or Record files
- SQLite databases or JSONL conversation histories
- machine-specific absolute paths
- private account links or personal identifiers
Recommended pre-publish check:
```powershell
$env:CODEX_TOOLKIT_PRIVATE_PATTERNS="<private markers separated by semicolons>"
./install/Test-CodexToolkit.ps1 -PackageClean
```
## Repository Layout
```text
.
├─ mcps/
│ ├─ broker/
│ ├─ memory-store/
│ ├─ mcp-subagent/
│ ├─ sandbox/
│ └─ web-fetcher/
├─ rules/
│ ├─ codex/
│ ├─ antigravity/
│ └─ claude-code/
├─ install/
├─ skills/
├─ templates/
├─ design-tests/
├─ PACKAGE_MANIFEST.md
├─ PRIVATE_EXCLUDE_CHECKLIST.md
├─ TOOLKIT_README.md
└─ SETUP.md
```
## License
MIT. See `LICENSE`.
