Vesper Agent Suite

CLI tool to manage AI agents, prompts, instructions, and skills for your workspace — for GitHub Copilot Chat in VS Code, and for Claude Code.

Vesper is a comprehensive agent suite that supercharges your AI coding assistant with specialized agents, reusable skills, and structured workflows. Everything below describes the default (Copilot) target; see Claude Code target for the second target.

Installation

# Global installation
npm install -g @mthanh/vespercli

# Or use with npx
npx @mthanh/vespercli <command>

Quick Start

# Initialize Vesper in your project
# (multi-select which platform(s) to set up — GitHub Copilot and/or Claude Code;
#  pass --target copilot,claude or --target all to skip the prompt)
vespercli init

# (Optional) Add local overrides to customize specific assets
vespercli add --agent code-reviewer code-planner

# Add skills (as local overrides)
vespercli add --skill aesthetic tailwind-shadcn

# List local overrides
vespercli list

# Update local overrides
vespercli update

Settings-based Asset Injection (New)

Vesper now integrates with VS Code by configuring workspace settings instead of copying the full asset catalog into your repo.

What vespercli init does

• Creates/updates .vscode/settings.json to point Copilot Chat at Vesper's packaged assets.
• Configures core MCP servers in .vscode/mcp.json:
  • vesper-indexing: Fast code search
  • sequential-thinking: Complex reasoning
  • memory: Persistent knowledge graph
• Does not copy agents/prompts/instructions/skills into your workspace.
• Still creates .github/agents/vesper.agent.md so you can select Vesper in Copilot Chat.

Vesper writes these VS Code settings:

• chat.agentFilesLocations
• chat.instructionsFilesLocations
• chat.promptFilesLocations
• chat.agentSkillsLocations

Example (illustrative):

{
	"chat.agentFilesLocations": [
		"${workspaceFolder}/.vesper/agents",
		"/absolute/path/to/vesper/assets/agents"
	],
	"chat.instructionsFilesLocations": [
		"${workspaceFolder}/.vesper/instructions",
		"/absolute/path/to/vesper/assets/instructions"
	],
	"chat.promptFilesLocations": [
		"${workspaceFolder}/.vesper/prompts",
		"/absolute/path/to/vesper/assets/prompts"
	],
	"chat.agentSkillsLocations": [
		"${workspaceFolder}/.vesper/skills",
		"/absolute/path/to/vesper/assets/skills"
	]
}

Local overrides (still supported)

If you want to customize a specific agent/prompt/instruction/skill, use vespercli add.

• vespercli add copies only the assets you select into .vesper/.
• Local copies in .vesper/ take precedence over the settings-based (package) assets.
• This is the recommended way to make small, intentional customizations without vendoring everything.

Migration from legacy .vesper/ installs

If Vesper detects a legacy install that previously copied assets into .vesper/, vespercli init will offer to migrate you to the settings-based approach.

• After migrating, you can keep any locally customized files as overrides.
• Everything else is discovered directly from the Vesper package.

Commands

vespercli init

Initialize Vesper in your workspace. Pick one or more platforms (GitHub Copilot and/or Claude Code) via a multi-select prompt; the CLI lays down the base setup for each, then the Vesper agent handles orchestration.

• Copilot: creates/updates .vscode/settings.json so VS Code discovers Vesper assets from the installed package.
• Claude Code: installs the user-level plugin catalog + this project's orchestrator/roster/context and .mcp.json.
• Shared: builds the code index once (both platforms' vesper-indexing read the same .vesper/index.db).

On re-init, currently-installed platforms are pre-checked; uncheck a platform to remove it (you'll be asked to confirm). Platform selection is always asked — -y / --force-default only default the follow-up questions, not the platform choice. In non-interactive runs, pass --target.

vespercli init                          # Multi-select platform(s), then initialize
vespercli init --target copilot,claude  # Set up both in one run (no prompt)
vespercli init --target all             # Every supported platform
vespercli init --target claude -y       # Non-interactive: Claude with default settings
vespercli init --path /my/project       # Specify workspace path

vespercli add

Add local overrides (copies) for agents, prompts, instructions, or skills into .vesper/.

# Add agents
vespercli add --agent <name> [name2...]
vespercli add -a code-reviewer code-planner

# Add prompts
vespercli add --prompt <name> [name2...]
vespercli add -p create-specification

# Add instructions
vespercli add --instruction <name> [name2...]
vespercli add -i nextjs reactjs

# Add skills
vespercli add --skill <name> [name2...]
vespercli add -s aesthetic backend-development

vespercli list

List local override assets in .vesper/.

vespercli list                    # List all local override assets
vespercli ls                      # Alias
vespercli list --type agents      # Filter by type
vespercli list -t skills          # Short form

vespercli update

Update local override assets from the package to get the latest versions.

vespercli update                  # Interactive confirmation
vespercli update -y               # Skip confirmation

vespercli reset

Remove Vesper configuration and/or local overrides.

vespercli reset                   # Interactive confirmation
vespercli reset -y                # Skip confirmation
vespercli reset --settings-only   # Only remove VS Code settings entries
vespercli reset --local-only      # Only remove local `.vesper/` folder
vespercli reset --full            # Remove EVERYTHING including vesper.agent.md (requires typing "YES")

vespercli --version

Display the current version.

vespercli -v
vespercli --version

vespercli --help

Display help information.

vespercli -h
vespercli --help
vespercli <command> --help

Asset Types

Vesper provides a full catalog via VS Code settings, and supports optional local overrides.

| Type | Discovered from Vesper package (settings-based) | Optional local overrides (copied by vespercli add) | |------|-----------------------------------------------|--------------------------------------------------| | Agents | assets/agents/ | .vesper/agents/ | | Prompts | assets/prompts/ | .vesper/prompts/ | | Instructions | assets/instructions/ | .vesper/instructions/ | | Skills | assets/skills/ | .vesper/skills/ |

After Installation

1. Open VS Code in your workspace
2. Open GitHub Copilot Chat (Ctrl+Shift+I / Cmd+Shift+I)
3. Select Vesper from the agent dropdown
4. Start working with an AI agent suite that includes specialized developers, planners, reviewers, and more

Claude Code target

Vesper also targets Claude Code, as a second, fully independent install alongside (or instead of) the Copilot target above — nothing here changes the default behavior of the commands described so far.

Claude Code has no equivalent of VS Code's chat.agentFilesLocations setting (no way to point it at an arbitrary external directory), so the specialist catalog is distributed as a user-level plugin instead of referenced in place: vespercli init --target claude installs it once to ~/.claude/skills/vesper/, and it's then available in every Claude Code project on the machine, not just this one. Only genuinely project-specific content lives in the repo:

vespercli init --target claude          # Install the plugin catalog + this project's orchestrator/roster/context

This creates, in the current project only:

• CLAUDE.md — a small guarded @import block pointing at the three files below (never touches the rest of your CLAUDE.md)
• .claude/vesper/orchestrator.md — the orchestration playbook (routing rules, delegation), refreshed on every init/update
• .claude/vesper/orchestration.md — this project's Team Roster + Task Management config
• .claude/vesper/context.md — this project's architecture/stack/conventions
• .mcp.json and .claude/settings.json — the vesper-indexing MCP server + its tool permissions

No .claude/agents/, .claude/commands/, or .claude/skills/ appear in the project — the full specialist catalog (subagents, slash commands, skills) lives once in the shared plugin at ~/.claude/skills/vesper/.

vespercli init --target claude                          # Install/refresh everything above
vespercli add agents code-reviewer --target claude       # Add one subagent to the plugin catalog
vespercli list --target claude                           # See what's installed
vespercli update --target claude                         # Refresh the plugin + orchestrator playbook after `npm update`
vespercli reset --target claude                           # Remove this project's files (leaves the shared plugin catalog alone)
vespercli mcp status --target claude                      # Check the vesper-indexing MCP server in .mcp.json

Unlike the Copilot target, this one has no editor dependency — ~/.claude/... and a project's .claude//CLAUDE.md/.mcp.json are read by the Claude Code engine itself, so the same install works whether you drive it from the plain terminal CLI, the VS Code extension, JetBrains, or the desktop app.

Mixed-target workspaces

A single project can have both targets installed at once — .vesper/ (the code index, story tracking, history.md) is shared and cross-client by design, so a story researched under Copilot can be picked up and implemented under Claude Code, or vice versa. .vesperrc records each target under its own key, so running init --target claude in an already-Copilot-initialized project adds a claude entry without touching the existing Copilot fields.

Naming and conflicts

vespercli init --target claude asks once whether to prefix the catalog's subagent/skill/command names with vesper- (to avoid collisions with other Claude Code kits you may have installed) or keep plain names (the default, matching the Copilot catalog's naming 1:1). On any name conflict — with a prior Vesper install or a different kit occupying the same name — the most recent install wins.

Requirements

• Node.js >= 22.13.0 (the vesper-indexing MCP server uses the built-in node:sqlite module)
• VS Code with GitHub Copilot, and/or Claude Code (CLI, VS Code extension, JetBrains, or desktop app)

License

MIT