vibe-kits 0.3.1

Portable engineering kits for AI coding tools.

Vibe Engineering

Portable engineering kits for AI coding tools. The vibe kits CLI installs context, rules, agents, and skills into Claude Code, OpenCode, Gemini CLI, Codex CLI, and Cursor, and scaffolds a local-first Obsidian/qmd second-brain vault with safe AI-agent config snippets — all without copying secrets or overwriting your existing config files. The second-brain kit optionally runs npm install -g @tobilu/qmd with your consent; all other kits run no network commands.

Available Kits

Kit key	Surface	What it does
claude-code	vibe kits claude-code …	Persona, rules, agents, commands, skills into ~/.claude
opencode	vibe kits opencode …	Same content, adapted to ~/.config/opencode layout + JSONC merge
gemini	vibe kits gemini …	Self-contained persona + rules into ~/.gemini/GEMINI.md
codex	vibe kits codex …	Self-contained persona + rules into ~/.codex/AGENTS.md
cursor	vibe kits cursor …	Seven .mdc rule files into ~/.cursor/rules/
second-brain	vibe kits second-brain …	Local Obsidian/qmd vault scaffold + non-secret AI-agent snippets

Install

# From PyPI (recommended)
pipx install vibe-kits

# From GitHub (latest unreleased)
pipx install git+https://github.com/kidboy-man/vibe-engineering.git

# Self-upgrade from the stable package channel
vibe upgrade

vibe kits list

# Claude Code
vibe kits claude-code doctor
vibe kits claude-code install --yes

# OpenCode
vibe kits opencode doctor
vibe kits opencode install --yes

# Gemini CLI
vibe kits gemini doctor
vibe kits gemini install --yes

# Codex CLI
vibe kits codex doctor
vibe kits codex install --yes

# Cursor IDE
vibe kits cursor doctor
vibe kits cursor install --yes

# Second Brain
vibe kits second-brain install --dry-run --yes
VIBE_SECOND_BRAIN_PATH="$HOME/notes" vibe kits second-brain install --yes
vibe kits second-brain doctor

Claude Code Kit

Portable Claude Code setup for senior backend engineering. The kit installs global Claude Code context files, modular rules, custom agents, and slash commands without copying secrets or machine-specific auth/proxy configuration.

Commands

vibe kits claude-code doctor
vibe kits claude-code install --dry-run
vibe kits claude-code install --yes
vibe kits claude-code diff
vibe kits claude-code uninstall --yes

What it installs

Managed files are copied into ~/.claude:

• CLAUDE.md global senior/staff backend engineering persona
• rules/*.md modular operating, Go backend, security/data, database/ops, testing, and uncertainty/source rules
• agents/*.md custom global agents for implementation, tech lead review, security/data review, DB/ops review, and TDD
• commands/*.md reusable slash commands
• selected portable skills, currently skills/vibe-engineering/SKILL.md
• a manifest at ~/.claude/.vibe-engineering-manifest.json

OpenCode Kit

Portable OpenCode setup for senior backend engineering. Mirrors the Claude Code kit's persona, rules, agents, and commands, adapted to OpenCode's directory layout and config format (AGENTS.md for persona, ~/.config/opencode/opencode.jsonc for config, ~/.config/opencode/{agents,commands,skills,rules}/ for the rest).

Commands

vibe kits opencode doctor
vibe kits opencode install --dry-run
vibe kits opencode install --yes
vibe kits opencode diff
vibe kits opencode uninstall --yes

What it installs

Managed files are copied into $XDG_CONFIG_HOME/opencode (default: ~/.config/opencode):

• AGENTS.md global senior/staff backend engineering persona
• rules/*.md modular operating, Go backend, security/data, database/ops, and testing rules
• agents/*.md custom global subagents for tech lead review, Go implementation, security/data review, DB/ops review, and TDD
• commands/*.md reusable slash commands (/trd, /review-go, /clone-setup)
• selected portable skills, currently skills/vibe-engineering/SKILL.md
• safe non-secret defaults merged into opencode.jsonc ($schema, lsp: true)
• a manifest at ~/.config/opencode/.vibe-engineering-manifest.json

The installer respects $XDG_CONFIG_HOME and ships a JSONC parser that strips // and /* */ comments and trailing commas so it can read your existing opencode.jsonc without losing it.

AGENTS.md merge behavior

Unlike most managed files, AGENTS.md is merged with any existing file, never overwritten. The installer injects the persona between <!-- vibe-engineering-kit:begin --> and <!-- vibe-engineering-kit:end --> markers, leaving your own rules above and below untouched. Re-installs replace only the content between the markers, so the persona body can be upgraded without disturbing your local content. vibe kits opencode uninstall strips the marked section; if no other content remains, the file is deleted.

<!-- vibe-engineering-kit:begin -->
# Global Engineering Persona
...kit content...
<!-- vibe-engineering-kit:end -->
# My Project Rules
...your content (preserved)...

Gemini CLI Kit

Portable Gemini CLI setup for senior backend engineering. Installs a single GEMINI.md file with the full persona, all six engineering rules, and specialist role descriptions embedded inline — no separate rule files needed since Gemini CLI reads a single global instructions file.

Commands

vibe kits gemini doctor
vibe kits gemini install --dry-run
vibe kits gemini install --yes
vibe kits gemini diff
vibe kits gemini uninstall --yes

What it installs

~/.gemini/GEMINI.md — a single self-contained file containing:

• senior/staff backend engineering persona and operating identity
• task risk policy and autonomy boundaries
• all six modular engineering rules (operating model, Go backend, testing, security/data, database/ops, uncertainty/sources) embedded as sections
• specialist role descriptions for all five subagent modes (backend-tech-lead, go-backend-implementer, security-data-reviewer, db-operations-reviewer, tdd-test-engineer)
• communication style and definition of done

Rules are embedded rather than referenced because Gemini CLI loads a single instructions file rather than a rules directory.

Codex CLI Kit

Portable Codex CLI setup for senior backend engineering. Installs a single AGENTS.md file with the same comprehensive persona and embedded rules.

Commands

vibe kits codex doctor
vibe kits codex install --dry-run
vibe kits codex install --yes
vibe kits codex diff
vibe kits codex uninstall --yes

What it installs

~/.codex/AGENTS.md — a single self-contained file with the same structure as GEMINI.md above, adapted to Codex CLI conventions. Project-level AGENTS.md files take priority over the global file.

Cursor IDE Kit

Portable Cursor IDE setup for senior backend engineering. Installs rule files into ~/.cursor/rules/ as .mdc files. Each file has YAML frontmatter (description, globs, alwaysApply) so Cursor can selectively load rules based on file type.

Commands

vibe kits cursor doctor
vibe kits cursor install --dry-run
vibe kits cursor install --yes
vibe kits cursor diff
vibe kits cursor uninstall --yes

What it installs

Seven .mdc files into ~/.cursor/rules/:

File	alwaysApply	Scope
00-persona.mdc	true	global persona, risk policy, autonomy, definition of done
operating-model.mdc	true	workflow, risk classification, scope discipline
security-and-data-safety.mdc	true	authz, secrets, injection, tenant isolation
uncertainty-and-sources.mdc	true	epistemic honesty, citation standards
go-backend-engineering.mdc	false	Go-specific rules; globs **/*.go
testing-and-verification.mdc	false	TDD, test quality; globs test file patterns
database-and-operations.mdc	false	migrations, queries, transactions; globs DB file patterns

Note: Cursor 0.45+ also supports project-local rules at .cursor/rules/. For per-project behavior, copy the relevant .mdc files from ~/.cursor/rules/ into your project's .cursor/rules/ directory and adjust as needed.

Second-Brain Kit

Local-first Obsidian + qmd vault with safe AI-agent config snippets. The kit creates a vault scaffold, seeds three wiki pages, and merges a non-secret qmd MCP entry into Claude Code, OpenCode, and Codex CLI configs. When qmd is not found, install prompts then runs npm install -g @tobilu/qmd and registers the wiki collection. Pass --no-setup-deps to skip; all other network commands (qmd, pip, git clone, etc.) are never run.

Vault location

• Default: ~/second-brain
• Override: VIBE_SECOND_BRAIN_PATH=/path/to/vault

The vault is your data. The installer creates it; uninstall never touches it. See the safety contract in the Safety Model section.

Commands

vibe kits second-brain install --dry-run --yes          # show plan, write nothing
VIBE_SECOND_BRAIN_PATH="$HOME/notes" \
    vibe kits second-brain install --yes                 # scaffold vault + agent snippets
vibe kits second-brain diff                              # what would change on next install
vibe kits second-brain doctor                            # health check (qmd, vault, agent configs)
vibe kits second-brain uninstall --yes                   # strip agent snippets + manifest only

All four commands accept --home <path> to redirect the agent config root (default $XDG_CONFIG_HOME or current user's home) — useful for isolated dry runs in CI. install also accepts --no-settings to skip the agent config adapters and only scaffold the vault.

What it creates in the vault

Directory scaffold (under the vault root, all create-if-absent):

raw/assets/                # unprocessed inputs
inbox/                     # new content waiting to be processed
wiki/
├── sources/learning/      # knowledge extracted from articles and talks
├── sources/journal/       # personal reflections
├── entities/projects/     # named projects and codebases
├── concepts/
│   ├── backend/           # extracted backend concepts
│   ├── ai-engineering/    # extracted AI/LLM concepts
│   ├── pkm/               # personal-knowledge-management concepts
│   └── personal/          # personal notes
├── synthesis/             # cross-source notes
├── index.md               # seed: vault map (frontmatter + content)
├── log.md                 # seed: rolling activity log
└── hot.md                 # seed: current focus / "in progress"
output/                    # rendered reports and exports
.claude/                   # local Claude config (separate from ~/.claude)

Files written by the installer:

• .gitignore — kit entries (node_modules/, .qmd/, .claude/settings.local.json) merged with any existing lines, no duplicates
• .git/ — git init -q, idempotent (skipped if .git already exists)
• .vibe-engineering-manifest.json — runtime manifest recording what was installed and the safety note that vault data is never uninstall-deleted

Seed pages are created only if absent and never overwritten on reinstall.

Agent config snippets

The installer merges a qmd MCP entry (command: qmd, args: ["mcp"]) into each agent's config using a format-specific safe adapter. No secrets, no full-file overwrites — unrelated keys, MCP servers, and settings are preserved byte-for-byte.

Agent	Format	Adapter	Scope
Claude Code	JSON	json_defaults_strategy	~/.claude/settings.json; skips env and secret keys
OpenCode	JSONC	jsonc_defaults_strategy	~/.config/opencode/opencode.jsonc; skips 14 local-only keys + 6 secret substrings
Codex CLI	TOML	toml_block_merge_strategy	~/.codex/config.toml; inserts/replaces [mcp_servers.qmd] block only
Cursor	JSON + MDC	cursor_hook_merge_strategy + kit-owned rule copy	~/.cursor/hooks.json sessionStart entry + ~/.cursor/rules/second-brain.mdc
Hermes	—	docs/sample only	No config mutation anywhere; ship docs only

qmd policy

qmd is the core search/index dependency. When qmd is not found, install prompts to run npm install -g @tobilu/qmd and register the wiki collection automatically. Pass --yes to skip the prompt; pass --no-setup-deps to skip auto-install entirely (you'll see the manual commands below). doctor returns 1 if qmd is missing or its collection list does not point at <vault>/wiki.

To install manually:

npm install -g @tobilu/qmd                  # Node >= 20
qmd collection add <vault>/wiki --name second-brain
qmd update                                  # build the initial index

Obsidian and memory compiler

• Obsidian is an optional visual client. If missing, doctor returns 0 with a warning. The vault works with any Markdown editor.
• Memory compiler is a docs-only add-on. The installer ships installation and hook-configuration docs under wiki/docs/ but never clones, configures, or mutates Claude settings for it.

Safety Model

All kits intentionally do not include or install:

• auth tokens, API keys, or passwords
• local router/proxy URLs
• provider / model selection (for OpenCode, also: plugin, mcp, theme, env, permission, agent)
• project transcripts, histories, tasks, caches, or backups
• local machine-specific MCP auth state

For the OpenCode kit, the top-level config keys model, provider, plugin, mcp, tools, permission, env, agent, theme, and any key containing token, key, secret, password, auth, or credential are always preserved as-is. The second-brain kit reuses the same policy via agents/secret_policies.py. The Gemini, Codex, and Cursor kits install only portable markdown/text files and never touch settings files or credentials.

The second-brain kit additionally guarantees:

• Controlled package-manager execution: second-brain install prompts then runs npm install -g @tobilu/qmd when qmd is not found, then registers the wiki collection. Pass --no-setup-deps or decline the prompt to skip. All other kits never run any package-manager command.
• No other network or install commands: never runs git pull, git clone, qmd embed, qmd init, or starts the qmd MCP daemon
• No symlinks: never creates cross-directory symlinks
• No plugin or Obsidian installs: obsidian is checked by doctor but never installed
• No memory-compiler hooks: never mutates .claude/settings.json for memory-compiler hooks
• No third-party skill redistribution: claude-obsidian is referenced as install commands only; its skill files are not copied into the repo
• Vault data is sacred: uninstall never deletes the vault directory, .git, seed pages, .gitignore, or any user content under raw/, wiki/, output/. It removes only kit-owned non-secret agent config snippets and the runtime manifest

Adding a new kit

The simplest kits (Claude Code / OpenCode shape) export four functions. The second-brain kit is the canonical example for kits that need a fake home parameter for testing, environment-variable overrides, multiple agent config adapters, and a safe-scaffold pattern that never deletes user data. Read its installer.py before designing a new kit of similar scope.

1. Create the installer module at agents/kits/<kit_name>/installer.py exporting four functions (the canonical signature, shared by every kit):

   • install(home=None, dry_run=False, yes=False, **kwargs) -> int
   • diff_kit(home=None) -> int
   • doctor(home=None) -> int
   • uninstall(home=None, dry_run=False, yes=False, **kwargs) -> int

   For kits that merge agent config snippets, gate the merge behind a boolean (the CLI exposes it as --no-settings). For kits that scaffold user data, treat that data as immutable: mkdir -p and create-if-absent seeds only; never rm or overwrite user files.

2. Add a KitSpec in agents/kit_registry.py pointing to those functions. The spec's help text is what shows up in vibe kits <name> --help.

3. Place templates and a manifest under agents/kits/<kit_name>/templates/<kit_name>/:

   • manifest.json with kit, version, managed_files, settings_fragment, and secret_policy
   • All files listed in managed_files

4. Add manifest contract tests in tests/test_manifest_contracts.py asserting every managed file exists and the manifest surface is valid.

5. If the kit merges JSON / JSONC / TOML / ENV, add or reuse a strategy in agents/merge_strategies.py. The second-brain kit added toml_block_merge_strategy and strip_toml_block; reuse them rather than re-implementing.

6. If the kit needs shared key/secret policy (the local-only and secret-substring sets used by both the OpenCode and second-brain JSONC adapters), import from agents/secret_policies.py instead of redefining locally.

No CLI dispatch code needs to change: build_parser(kit_specs=KITS) reads the registry dynamically.

Development

python3 -m unittest discover -s tests -v

Inside an activated virtualenv where python points to Python 3, python -m unittest discover -s tests -v is also acceptable.

The full suite covers kit registry, CLI contract, extension contract, manifest contracts, installer behavior (install / diff / doctor / uninstall) for every kit, and the shared merge strategies. All tests must pass before shipping.