Monorepo

One VPS workspace, many AI agents.

Monorepo is a minimal filesystem scaffold for using several coding agents against the same files. It keeps one canonical instruction layer, one shared skill library, and thin compatibility adapters for agents that expect different filenames or directories.

It is intentionally boring: Markdown, symlinks, shell scripts, and config templates.

What It Does

• Uses AGENTS.md as the canonical project instruction file.
• Generates CLAUDE.md for Claude Code.
• Generates workspace files such as SOUL.md, TOOLS.md, USER.md, IDENTITY.md, and HEARTBEAT.md.
• Stores reusable skills in _shared/skills/*/SKILL.md.
• Exposes shared skills through .agents/skills, .claude/skills, .pi/skills, and skills.
• Provides opt-in global links for ~/.agents, ~/.codex, ~/.claude, ~/.pi, and ~/.hermes.
• Avoids daemons, databases, proprietary services, and custom agent runtimes.

What It Does Not Do

• It does not replace hidden vendor system prompts.
• It does not guarantee identical behavior across agents.
• It does not sync devices by itself. Use Git or your normal file sync process.
• It does not manage secrets or credentials.
• It does not overwrite home-directory files unless you run scripts/bootstrap.sh --apply.

Quick Start

cd ~/monorepo
scripts/sync.sh
scripts/doctor.sh
scripts/bootstrap.sh --dry-run

If the dry run looks right:

scripts/bootstrap.sh --apply
scripts/doctor.sh --global

Core Layout

monorepo/
├── AGENTS.md
├── CLAUDE.md
├── SOUL.md
├── TOOLS.md
├── USER.md
├── IDENTITY.md
├── HEARTBEAT.md
├── skills -> _shared/skills
├── .agents/skills -> ../_shared/skills
├── .claude/skills -> ../_shared/skills
├── .pi/skills -> ../_shared/skills
├── _shared/
│   ├── instructions/
│   ├── skills/
│   ├── prompts/
│   └── claude-agents/
├── _global/
├── projects/
├── scripts/
└── config/

Daily Workflow

cd ~/monorepo
scripts/sync.sh
scripts/doctor.sh

Then run whichever agent you want from the workspace:

codex
claude
pi
hermes
openclaw

Editing Instructions

Edit files in _shared/instructions/, then run:

scripts/sync.sh

Generated files include a header and should not be edited directly.

Adding Skills

Create a folder under _shared/skills/:

_shared/skills/my-skill/SKILL.md

Use frontmatter with at least name and description:

---
name: my-skill
description: Use when the agent needs to do the repeatable workflow this skill describes.
---

# My Skill

Steps go here.

Run:

scripts/doctor.sh

Adding Projects

scripts/new-project.sh my-project

Each project can have its own AGENTS.md and optional CLAUDE.md. Keep nested instructions local to that folder.

Agent Support

See docs/agent-support.md.

The design principle is simple: let each agent read the files it already expects.

VPS Model

The intended deployment is:

MacBook / iPhone / terminal
        ↓ SSH
VPS running ~/monorepo
        ↓
Codex, Claude Code, Pi, Hermes, OpenClaw

All agents operate on the same filesystem. Git handles cross-device sync.

Safety

Global linking is opt-in. scripts/bootstrap.sh defaults to dry-run mode and backs up conflicting paths before creating symlinks.

Do not store secrets in this repo.