autoresearch

AI Workspace

Manage shared AI agent skills, configs, and automation across multi-repo workspaces. Works with Cursor, Claude Code, Codex, Amp, and 40+ AI coding tools.

The problem: AI agents only see the repo they run in. An agent working in a frontend repo has no visibility into the backend, API contracts, or shared conventions -- so it assumes and hallucinates. On top of that, each developer configures AI tools differently, so skills, instructions, rules, and MCP servers drift between projects and team members.

The solution: A single workspace/ repo that acts as the canonical source. Running npm install mirrors configs to the parent root, symlinks skills and MCP servers for every AI tool, and installs git hooks to keep everything in sync.

Quick Start

Create a new workspace (one-time, by whoever sets it up):

mkdir ~/dev/<your-org> && cd ~/dev/<your-org>
npx aiworkspace init
cd workspace
git remote add origin <your-repo-url>
git push -u origin main

Join an existing workspace (every other team member):

cd ~/dev/<your-org>
git clone <your-teams-workspace-repo> workspace
cd workspace && npm install

npm install restores skills from the lockfile, mirrors configs to the parent root, creates skill symlinks, and installs git hooks. See setup.md for the full guide — including MCP secrets (cp .env.example .env.local, restart editor).

How It Works

~/dev/<your-org>/                       <- open this in Cursor / your editor
├── workspace/                          <- this repo
│   ├── root-config/                    <- canonical source for root-level AI configs
│   │   ├── AGENTS.md                   <- standing instructions for all AI tools
│   │   ├── .agents/mcp.json            <- canonical MCP servers (single source of truth)
│   │   ├── .agents/skills/             <- workspace-wide skills
│   │   ├── .mcp.json, .cursor/, .codex/, .vscode/   <- per-editor configs (symlinked or generated)
│   │   ├── .env.example                <- template for MCP secrets (-> .env.local at root)
│   │   └── skills-lock.json            <- lockfile for workspace-wide skills
│   ├── .agents/skills/                 <- workspace project-specific skills
│   ├── scripts/                        <- automation (setup, hooks, skill wrappers)
│   └── package.json
├── <project-a>/                        <- your app / service / library
├── <project-b>/
└── ...

The setup script walks root-config/ generically. Add new config types (Cursor rules, Claude settings, Codex config) and they sync automatically with no script changes.

Tools that write their own config

Run a tool's init inside root-config/ and its output mirrors to the workspace root like anything else. OpenSpec is the worked example — one spec tree shared across every repo.

• Git cannot see empty directories, so they never mirror — add a .gitkeep.
• Directories the workspace also populates, such as .claude/skills/, are merged, not replaced.

Nested workspaces

A project directory can hold a workspace of its own — a team repo cloned with its own workspace/root-config/. Setup treats that as a boundary: it stops at any directory that is, or contains, a workspace repo and never links inside it. The whole subtree belongs to that workspace, project repos several levels down included.

~/dev/<your-org>/
├── workspace/                 <- this workspace, manages the tree below
├── <project-a>/               <- linked
└── <team-b>/                  <- SKIPPED: has its own workspace
    ├── workspace/             <-   ...here
    └── <their-project>/       <-   theirs to link, not ours

Run npm run skills:setup inside the nested workspace to manage that subtree. Explicit setup and sync runs name each boundary they skip; the git hooks stay quiet.

Knowledge Hierarchy

Everything follows nearest-wins: the closer a file is to the code being changed, the higher its priority.

Skills

npm run skills:add -- <source> [--project <repo>]      # add from registry
npm run skills:add -- owner/repo --skill <name>         # pick from multi-skill repo
npm run skills:remove -- [<skill>] [--project <repo>]   # remove
npm run skills:create -- --name my-skill                # create manually
npm run skills:list                                      # list installed
npm run skills:find                                      # search skill registry
npm run skills:update                                    # update all
npm run skills:check                                     # check for available updates
npm run skills:setup                                     # re-sync configs and symlinks

Without --project, skills install to root-config/.agents/skills/ (workspace-wide). With --project <repo>, they go to <repo>/.agents/skills/ (project-only).

Skills are tracked in skills-lock.json (source + hash). On npm install, they are restored from the lockfile automatically.

MCP

MCP servers give agents shared tools. Define them once in root-config/.agents/mcp.json and every editor picks them up — no per-developer setup. context7 (up-to-date library docs) ships bundled.

To add or change a server, edit .agents/mcp.json, then regenerate the twins and symlinks:

npm run sync

Sync refreshes bundled servers from the aiworkspace template and preserves any servers you added. Local edits to a bundled server are overwritten on the next sync — to override one for a single repo, use <project>/.cursor/mcp.json (nearest-wins).

To drop a bundled server entirely, list it in root-config/.agents/mcp-disabled.json ({ "disabled": ["context7"] }) — deleting it from .agents/mcp.json alone won't stick, since sync restores bundled servers from the template.

Secrets. Servers that need tokens read them from .env.local at the parent workspace root:

cp .env.example .env.local     # then fill in tokens, and restart your editor
npm run mcp:check-secrets      # verify tokens are present

Stdio servers using ${VAR} are wrapped automatically to load .env.local. See setup.md §4.1 for HTTP Bearer servers in Cursor and OAuth sign-in for Codex.

Env var naming. If you load .env.local into your shell (via npm run mcp:install-shell or a manual source in ~/.zshrc), those keys become part of your login environment. Prefer a workspace-specific prefix on secret names in .env.example and mcp.json (e.g. ACME_SONAR_TOKEN instead of SONAR_TOKEN) so they do not collide with other tools or p