Why Vnmese

Vnmese makes AI coding agents read the project before they write. It scans conventions, builds a code impact tree, injects required context into agent sessions, adds coding roles and skills, and guards MCP-backed edits behind confirmation.

Install one package only: vnmese. The core engine, MCP server, skills, roles, and Codex adapter are bundled into that package.

Quick Start

Install Vnmese in a project:

npm install -D vnmese

Because this is a local project dependency, call it with npx, npm exec, or an npm script:

npx vnmese init
npm exec vnmese -- init

Optional scripts:

{
  "scripts": {
    "vnmese": "vnmese",
    "vnmese:init": "vnmese init"
  }
}

Then:

npm run vnmese:init
npm run vnmese -- status

If you want vnmese and vnm available globally:

npm install -g vnmese
vnmese init
vnm init

Init Flow

npx vnmese init

During init, Vnmese will:

1. Ask which agent environment you use: Claude Code or Codex.
2. Detect JavaScript/TypeScript project languages.
3. Scan convention files such as CLAUDE.md, AGENTS.md, README.md, CONTRIBUTING.md, and docs/*.
4. Ask which context files should be injected into agent sessions.
5. Create .vnmese/config.json, .vnmese/lessons.md, .vnmese/history.json, and .vnmese/tree.json.
6. Create .mcp.json for Claude Code projects.
7. Show the base Vnmese mascot.
8. Ask whether you want to choose a role immediately.

Check setup:

npx vnmese status

Build or refresh the code tree:

npx vnmese tree

Run Claude with Vnmese integration:

npx vnmese run claude

Run Codex with Vnmese context injection:

npx vnmese run codex -- "fix the failing tests"

How It Works

| Step | What happens | Command | | --- | --- | --- | | 1 | Initialize project context and build the first tree | npx vnmese init | | 2 | Inject context into the agent session | npx vnmese run claude | | 3 | Choose a coding persona when useful | /role security | | 4 | Guard risky writes through MCP | vnmese_write_file | | 5 | Approve, reject, or override pending edits | npx vnmese confirm --watch |

Generated Files

Vnmese creates runtime files in the target project:

.vnmese/
├── config.json
├── lessons.md
├── history.json
├── pending.json
└── tree.json

tree.json, pending.json, and backup files are runtime artifacts and should not be committed.

For Claude Code, Vnmese also creates:

.mcp.json

Example:

{
  "mcpServers": {
    "vnmese": {
      "command": "npx",
      "args": ["vnmese", "mcp"]
    }
  }
}

Role System

Roles are session-scoped coding personas. They do not persist in config.json, and they disappear when the Claude Code/MCP session ends.

Choose a role from terminal:

npx vnmese role
npx vnmese role security
npx vnmese role implement

With the short alias:

npx vnm role
npx vnm role review

Inside Claude Code, use the role prompt:

/role
/role security

If your MCP client exposes prompts with namespaced names, use:

/mcp__vnmese__role
/mcp__vnmese__role security

Switching role:

• Shows the selected role mascot.
• Introduces the role and related skills.
• Overrides the active role persona for the current MCP session.
• Appends role context to Vnmese force-read context.
• Keeps conversation history intact.
• Does not write active role to disk.

Available roles:

| Core | Specialist | Ops | | --- | --- | --- | | architect | security | devops | | implement | performance | docs | | review | a11y | | | debug | memory-leak | | | test | database | | | refactor | dependency | |

Context Injection

Print the prompt payload Vnmese injects:

npx vnmese context --format prompt

List configured force-read files:

npx vnmese context --list

JSON output for wrappers:

npx vnmese context --format json

Context payload includes:

• selected force-read files
• .vnmese/lessons.md
• relevant lessons
• active role persona when a session role is active

Claude Code MCP

Vnmese exposes guarded MCP write tools:

vnmese_write_file
vnmese_edit_file

Agents should use these tools for writes. When a guarded write/edit request arrives, Vnmese:

1. Validates that the path stays inside the project root.
2. Requires .vnmese/tree.json to exist.
3. Runs impact analysis.
4. Creates a pending token in .vnmese/pending.json.
5. Waits for user confirmation through the confirm bridge.

Run the confirm bridge:

npx vnmese confirm --watch

Confirm actions:

• y / yes: approve the edit.
• n / no: reject the edit.
• o / override: allow the edit and preserve an override audit event.

MCP prompts:

vnmese-context
role
vnmese-review
vnmese-debug
vnmese-audit
vnmese-impact
vnmese-explain
vnmese-test-gen
vnmese-refactor
vnmese-learn

Codex

Run Codex through Vnmese:

npx vnmese run codex -- "review this module"

Vnmese injects context through:

OPENAI_SYSTEM_PROMPT
VNMESE_ACTIVE=1
VNMESE_PROJECT_ROOT=<project root>

Current limitation: Codex integration is context-only. Guarded file-write enforcement is handled through MCP tools.

Skills

List available skills:

npx vnmese skills

Run skills:

npx vnmese impact src/auth.ts::login
npx vnmese explain src/auth.ts::login
npx vnmese review src/auth.ts
npx vnmese debug src/api.ts::handler
npx vnmese audit src/
npx vnmese test-gen src/auth.ts::login
npx vnmese refactor src/auth.ts::login simplify

Most skills need a current tree:

npx vnmese tree

Lessons

npx vnmese lessons
npx vnmese lessons --query validation
npx vnmese lessons --format prompt --limit 10
npx vnmese lessons --delete src/auth.ts::login

History

Vnmese writes audit events to .vnmese/history.json for confirm decisions and skill runs.

npx vnmese history
npx vnmese history --overrides
npx vnmese history --type skill --skill review
npx vnmese history --json

Common Commands

npx vnmese init
npx vnmese status
npx vnmese tree
npx vnmese context --format prompt
npx vnmese role
npx vnmese role security
npx vnmese skills
npx vnmese confirm --watch
npx vnmese run claude
npx vnmese run codex -- "fix the bug"