Shofer is the open-source AI coding agent for VS Code with unparalleled parallelism, usability and observability. Run many agents at once, watch the whole task tree execute as live diagrams, and keep every command inside a kernel-level sandbox — on top of all the standard features you expect from your AI-powered development environment.
Welcome to Shofer (from the French chauffeur — driver). This manual covers the concepts and configuration you need to use Shofer effectively.
- Getting Started
- Settings
- Custom Modes
- Auto-Approval
- Parallel Tasks & Sub-tasks
- MCP Servers
- Semantic Code Search (RAG)
- Skills
- Git Worktrees
- Per-Task Cost Limit
- Slash Commands
- Special Files
- Live Memory
- Community
| UI Element | Purpose |
|---|---|
| Chat View | Interact with the AI — type messages, see results |
| Task Selector | Switch between multiple parallel tasks in a tree hierarchy |
| Mode Selector | Choose Code, Architect, Debug, Code Search, Web Search, Reviewer, or a custom mode |
| API Config Selector | Pick which AI provider and model to use per task |
| Worktree Selector | Create and select git worktrees for isolated parallel work |
| File Changes Panel | Review, accept, revert, or diff every file Shofer modifies |
| Context Window Bar | Monitor token usage and cost for the current task |
Shofer ships with six built-in modes that control which tools the AI can use:
| Mode | Icon | Best For |
|---|---|---|
| Code (default) | 💻 | Writing, modifying, and refactoring code. Broadest access. |
| Architect | 🏗️ | Planning and designing before writing code. |
| Debug | 🪲 | Troubleshooting errors and diagnosing root causes. |
| Code Search | 🔎 | Navigating and explaining the codebase — read-only. |
| Web Search | 🌐 | Researching with web and browser tools. |
| Reviewer | 👀 | Reviewing changes and inspecting work. |
You can add any number of custom modes via .shofer/shofermodes — and a custom mode of the same slug overrides a built-in one.
An API Provider Profile bundles your API key, model selection, and endpoint URL into a named configuration. Switch between profiles via the API Config Selector dropdown. Each task remembers its profile — switching tasks restores that task's profile.
Shofer supports true parallel tasks organized in a tree hierarchy. Use the Task Selector dropdown in the Task Header to switch between them:
- Colored dots show each task's state: Idle (gray), Running (green), Waiting for Input (yellow), Waiting on Subtask (blue), Paused (orange), Completed (green ✓), Error (red)
- Completed tasks carry a self-assessed rating: Poor, Well, or Excellent
- Pin important tasks to keep them at the top, Archive completed ones, Rename or Delete as needed
- Parent-child hierarchy — subtasks indent under their parent in the list
Once a task is running, the chat view shows:
| Element | What It Shows |
|---|---|
| Task Header | Task title, state dot, context window bar, todo list progress |
| Context Window Bar | Horizontal bar filling up as tokens accumulate; hover for counts |
| API Cost | Running total in USD, with inline pencil to edit the cost limit |
| File Changes Panel | Collapsible list of every file modified, with Accept / Revert |
| Message Queue | Messages you typed while Shofer was busy, with Send Now button |
Shofer's settings are organized by tab in the Settings panel (⚙️ gear icon):
| Tab | What You Configure |
|---|---|
| Providers | API profiles, models, endpoints, pricing overrides |
| Auto-Approve | Toggle which tool categories run without asking permission |
| Tools | Global tool disable list and tool group assignments |
| Slash Commands | Configure built-in and custom slash commands |
| Skills | Browse, load, and manage skill packs |
| Checkpoints | Git-based workspace snapshots for diff and revert (a bundled plugin) |
| Notifications | Telemetry, error reporting, and notification preferences |
| Live Memory | Configure the persistent read-only AI companion |
| Context | Adjust condensation thresholds and context window limits |
| Terminal | Configure command execution timeouts and allowlists |
| RAG Indexer | Semantic code and git log search index configuration |
| Modes | Create and edit built-in and custom modes |
| MCP Servers | Connect external tools (browser, databases, Kubernetes) |
| Prompts | Customize per-mode system prompts and instructions |
| UI | Chat view and sidebar display preferences |
| Experimental | Feature flags and opt-in experimental capabilities |
| Language | Change the display language |
| About | Export, import, or reset all Shofer settings |
Settings → About → Export archives your user scope's .shofer/ tree as shofer-settings.tgz — settings, provider profiles (never their API keys), modes, MCP servers, commands, rules and skills. Import unpacks such an archive into ~/.shofer. Reset wipes everything to defaults. API keys are never in the archive; re-enter them after an import.
Define custom modes in a .shofer/shofermodes file at your project root (or globally at ~/.shofer/shofermodes).
| Field | Purpose |
|---|---|
groups |
Grants broad categories of tools (read, write, execute, mcp, browser, mode, subtasks, questions) |
tools_allowed |
Grants individual tools outside the listed groups |
tools_denied |
Unconditionally blocks specific tools (always wins) |
Rule: (in groups OR in tools_allowed) AND NOT in tools_denied
Read-only reviewer:
customModes:
- slug: my-reviewer
name: 🔍 My Reviewer
roleDefinition: You are a code reviewer. You read code, find issues, and propose fixes — but you never edit files.
groups:
- readDocs-only editor (write restricted to Markdown):
- slug: docs-editor
name: 📝 Docs Editor
roleDefinition: You write and edit documentation.
groups:
- read
- - write
- fileRegex: "\\.(md|mdx)$"A mode must have at least groups or tools_allowed. Project-level modes override global modes with the same slug.
Auto-approval controls when Shofer acts without asking permission. Configure it via the AutoApproveDropdown (shield icon) in the chat input bar.
| Toggle | Controls |
|---|---|
| Read-Only | Reading files, searching code, listing directories |
| Write | Creating, editing, deleting files |
| Execute | Running shell commands |
| Browser | Browser automation tools |
| MCP | MCP tool calls and resource access |
| Mode | Switching between modes |
| Subtasks | Spawning and managing background tasks |
| Questions | Auto-selecting follow-up question answers |
Each mode has its own set of toggles. Toggling Read-Only ON in Code mode does not affect Architect mode.
The Execute toggle requires a list of allowed command prefixes to have any effect. When enabled, each shell command is matched against the allowlist using a "longest prefix wins" rule. A denylist can override specific commands.
Security: Start with toggles OFF and enable incrementally. Use the denylist for destructive commands (rm, git push --force). Keep "Protected Files" and "Outside Workspace" options OFF unless you genuinely need them.
Shofer can run multiple tasks at the same time. Start a new task from the title bar — your current task moves to the background.
The model spawns children with new_task. A child always runs concurrently: the parent gets the child's ID straight away and keeps working. Results and questions both arrive in the parent's mailbox.
| Tool | Purpose |
|---|---|
check_task_status |
Query a child's state |
send_message |
Put an envelope in another task's mailbox |
reply |
Answer a request in this task's mailbox |
wait |
Read this task's mailbox, parking until mail lands |
list_background_tasks |
List all running children |
cancel_tasks |
Stop children early |
A finished child's result is delivered to the parent as mail, so a parent that needs it before it can continue calls wait naming that child.
When a child needs clarification, you see the question in the child's own chat and its parent receives the same question as mail. Either of you may answer — whoever answers first wins, and the question disappears from the other side. If nobody answers within 10 minutes, the child is told to decide for itself. Canceling a parent automatically cancels all its children.
- Background tasks are aborted when their parent finishes or is stopped.
- After a VS Code restart, running tasks are reset to Idle.
Connect external tools via MCP (Model Context Protocol) servers. Configure them in Settings → Tools → MCP Servers (global) or .shofer/mcp.json (project).
Local Node.js server (stdio):
{
"my-tools": {
"type": "stdio",
"command": "node",
"args": ["./mcp-servers/my-tools/dist/server.js"],
"timeout": 60
}
}Remote HTTP server:
{
"arkware-tools": {
"type": "streamable-http",
"url": "http://localhost:30089"
}
}Assign tool groups to control auto-approval per tool:
{
"readonly-server": {
"command": "node",
"args": ["server.js"],
"toolGroups": {
"search_tool": "read",
"fetch_tool": "read"
}
}
}Disable individual tools with disabledTools, or an entire server with "disabled": true. Config files are watched automatically — saving triggers a reconnect.
Shofer can build a semantic search index of your codebase using Qdrant and an embedding provider. Once configured, the agent can use rag_search to find code by meaning.
- Have a running Qdrant instance.
- Choose an embedding provider (OpenAI, Ollama, Gemini, etc.) in Settings → RAG / Code Index.
- Enter credentials and enable indexing.
Shofer scans workspace files, builds embeddings, and stores them in Qdrant. The indexing status badge in the chat input bar shows progress.
rag_search complements lsp_search (symbol search) and grep_search (text search) — the agent picks the right tool automatically. Git commit history can also be indexed via the same infrastructure (Settings → RAG / Code Index → Git History).
Shofer can also index your git commit history for semantic search. When enabled (Settings → RAG Indexer → Git History), git_search lets the agent search commit messages by meaning — discovering who changed what, when, and why without exact keyword matching.
| Aspect | Code Index (rag_search) |
Git Index (git_search) |
|---|---|---|
| What it searches | Source code (functions, classes, comments) | Commit messages (subject + body) |
| Qdrant collection | ws-<hash> |
git-<hash> |
| Embedding provider | Shared (same as code index) | Shared |
| Result fields | File snippets with scores | Commit hash, author, date, subject, body, score |
Enable it by toggling Git History in the RAG Indexer popover or Settings → RAG Indexer. Configure max history days, max commits, and poll interval. Once indexed, the agent automatically uses git_search alongside rag_search when historical context would help.
Skills are reusable instruction packs for specific tasks. Each skill is a folder with a SKILL.md file.
| Directory | Scope |
|---|---|
{project}/.shofer/skills/ |
Project |
~/.shofer/skills/ |
Global |
.shofer/skills/
└── my-skill/
└── SKILL.md
SKILL.md uses YAML frontmatter followed by markdown instructions:
---
name: my-skill
description: Brief description (1-1024 characters)
modeSlugs:
- code
- architect
---
# My Skill
Full instructions Shofer will follow when this skill is loaded...Skills are discovered automatically. Use the 🎓 button in the chat input bar to browse and load them. Project-level skills override global skills with the same name.
Shofer manages git worktrees for parallel tasks, letting multiple tasks run on different branches simultaneously in the same VS Code window. Worktrees live under .worktrees/.
Worktrees are a bundled plugin, enabled by default (Settings → Plugins → Worktrees). Disable it and every task simply runs in the workspace.
A task you start without picking anything gets a fresh worktree on a new branch off your current HEAD, so two agents never edit the same files. Click the branch chip in the chat input to pick an existing worktree instead, or the current branch to opt out for that task.
- Click the branch chip in the chat input bar.
- Click "Create new worktree…".
- Confirm the branch and path (auto-generated).
- It becomes the selection for your next message.
By default, only tracked git files are present in a new worktree. Create a .shofer/worktreeinclude file to specify which gitignored files (e.g., node_modules/) to copy automatically. Only files matching both .gitignore and .shofer/worktreeinclude are copied.
Manage worktrees from Settings → Plugins → Worktrees (view, delete, force-delete with uncommitted changes). Multi-root workspaces are not supported.
Six slash commands handle the merge back: /merge-worktree,
/merge-worktree-cleanup, /rebase-worktree, /rebase-worktree-cleanup,
/dryrun-rebase-worktree and /worktree-status. They auto-detect the base branch, stop
rather than guess at an ambiguous conflict, and never push.
When a worktree is active, shell commands run inside an OS-level write-only
sandbox (Landlock / bwrap) that confines writes to the active worktree, and
rename_symbol edits are scoped to it — so parallel agents cannot write outside
their own checkout. See
Worktree Shell Sandboxing
for the confinement model.
Limitations:
- Submodules are initialized shallowly (
--depth 1) when the "Initialize submodules" option is left on; a repository needing full history must rungit submodule updateitself. - Nothing is ever pushed for you.
Set a USD budget cap on any task. When reached, Shofer pauses, aborts, or kills the task.
Edit a running task's cap by clicking the wallet icon next to the cost display in the Task Header. Actions: pause (ask you what to do), abort (clean stop), kill (immediate stop).
The displayed cost includes all descendant sub-tasks.
Slash commands are quick actions you can trigger by typing / in the chat input bar. Shofer ships with built-in commands and supports custom commands defined in your project.
| Command | Purpose |
|---|---|
/init |
Analyze your codebase and create an AGENTS.md file |
/migrate-from-roocode |
Migrate settings and modes from Roo-Code |
/migrate-from-copilot |
Migrate settings from GitHub Copilot |
/loaded |
List skills currently loaded into the task context |
/search |
Search for skills by keyword |
Define your own slash commands as .md files under .shofer/commands/ (project) or ~/.shofer/commands/ (global). Each file name becomes the command name.
---
description: Summarize the current project structure
modeSlugs:
- code
- architect
---
Read the project structure and provide a concise summary of the architecture, key directories, and entry points.Commands accept arguments — everything after /command-name is passed to the command template as $ARGUMENTS. Use the Settings → Slash Commands tab to browse and manage all registered commands.
Shofer recognizes these files in your project:
| File / Directory | Purpose | Location |
|---|---|---|
.shofer/shoferignore |
Hides files from the AI (.gitignore syntax) |
Workspace root |
.shofer/shofermodes |
Custom AI modes for this project | Workspace root |
AGENTS.md |
Project rules injected into every task | Workspace root |
.shofer/rules/ |
Mode-agnostic rules (always active) | Project or ~/.shofer |
.shofer/rules-<mode>/ |
Rules active only in a specific mode | Project or ~/.shofer |
.shofer/commands/ |
Slash commands | Project or ~/.shofer |
.shofer/skills/ |
Domain-specific skills | Project or ~/.shofer |
.shofer/mcp.json |
MCP server config for this project | Workspace .shofer/ |
The AI cannot modify these files without explicit approval: .shofer/shoferignore, .shofer/shofermodes, everything inside .shofer/, .vscode/settings.json, *.code-workspace, AGENTS.md.
Same syntax as .gitignore. Files matching the patterns are invisible to Shofer's tools. The "Show ignored files" setting (in Settings) controls whether ignored files appear in directory listings with a 🔒 badge.
Live Memory is a persistent, read-only AI companion that accumulates codebase knowledge over time — surviving task completion and VS Code restarts.
- Runs on a low-cost model with a large context window (you choose the model)
- Conversation history persists across tasks and VS Code restarts
- Learns organically — each question asked by a task adds context
- Strictly read-only — can only read files, search code, and look up symbols. Cannot write, execute, or use MCP tools
Any task can call the ask_live_memory tool to ask Live Memory a question. The agent answers from its accumulated knowledge, saving the calling task from re-loading files into its own context window.
- Open Settings → Plugins → Live Memory. It is enabled out of the box, but it stays dormant until you allow its billed AI calls — grant that consent there.
- Link an API Configuration profile with a lightweight model (e.g., Gemini Flash, GPT-4o-mini, Claude Haiku)
- The agent starts with an empty context and fills it as tasks ask questions
The Live Memory Status badge in the Shofer sidebar shows whether the agent is active and processing.
- Context reuse — knowledge persists across tasks, no redundant file loading
- Cost efficient — uses a cheap model; each answer costs a fraction of a cent
- KV-cache friendly — append-only context window keeps the provider's attention cache warm
- File-aware — notified of file changes to keep its knowledge fresh
Read the full Live Memory documentation
- Discord — Chat with the team, get help, share feedback
- Reddit — Community discussions and tips
- GitHub Issues and Feature Requests — Bug reports, feature requests, and tracking
Shofer is open source (Apache 2.0). Contributions are welcome — read CONTRIBUTING.md and check the roadmap.