Back2Base · ramseymcgrath · Jun 5, 2026 · Jun 5, 2026 · Jun 5, 2026 · Jun 5, 2026
diff --git a/README.md b/README.md
@@ -127,7 +127,7 @@ All variables are read from `~/.config/back2base/env` (or your shell, for proces
 | `BACK2BASE_ANTHROPIC_API_KEY` | Anthropic API key (pay-as-you-go). Alternative to the OAuth token. |
 | `BACK2BASE_ANTHROPIC_AUTH_TOKEN` | Custom auth bearer token for an Anthropic-compatible endpoint. |
 | `BACK2BASE_ANTHROPIC_BASE_URL` | Custom Anthropic-compatible base URL (e.g. a self-hosted proxy). |
-| `BACK2BASE_PROFILE` | Default MCP profile to load (`full`, `go`, `frontend`, `infra`, …). `last` resolves to the last profile used in this namespace. |
+| `BACK2BASE_PROFILE` | MCP profile to load. Defaults to `auto` (fingerprint the workspace). Set a name (`full`, `go`, `frontend`, `infra`, `general`, …) to pin one; `last` resolves to the last profile used in this namespace. |
 | `BACK2BASE_MODEL` | Force a specific Claude model alias. Unset = the selected profile's pinned model (default `claude-opus-4-8[1m]`). |
 | `BACK2BASE_DATA_DIR` | Host directory for persistent plans + memories. See [below](#persisting-plans-and-memories). |
 | `BACK2BASE_MANAGED_SETTINGS_DIR` | Override the host path probed for [enterprise managed policy](#enterprise-managed-policy). |
@@ -142,16 +142,17 @@ Optional per-tool MCP credentials (`GITHUB_TOKEN`, `DD_API_KEY` / `DD_APPLICATIO
 
 ### Profiles and models
 
-A profile narrows which MCP servers (and which model) a session loads. Pick one per run:
+A profile narrows which MCP servers (and which model) a session loads. The default is **`auto`**, which fingerprints your workspace at startup (e.g. `go.mod` → Go tools, `package.json` → frontend tools, `*.tf` → infra) and loads only the matching servers — keeping the cached tool prefix small and turns fast. Override per run:
 
 ```bash
-oss-back2base --profile go        # backend Go work
+oss-back2base                     # default → auto-detect from the workspace
+oss-back2base --profile go        # force the Go server set
 oss-back2base --profile frontend  # web / TypeScript
+oss-back2base --profile full      # every server (max capability, highest token cost)
 oss-back2base --profile minimal   # filesystem + git only
-oss-back2base                     # no flag → interactive picker on launch
 ```
 
-Built-in profiles: `full`, `go`, `python`, `frontend`, `infra`, `research`, `documentation`, `minimal`. Every profile includes the `core` servers (`filesystem`, `git`). The default model pinned by the profiles is `claude-opus-4-8[1m]`; override per-run with `BACK2BASE_MODEL`. Edit or add profiles in [`back2base-container/defaults/profiles.json`](back2base-container/defaults/profiles.json).
+Built-in profiles: `auto` (default), `full`, `go`, `python`, `frontend`, `infra`, `research`, `documentation`, `general` (lean fallback when nothing is detected), `minimal`. Every profile includes the `core` servers (`filesystem`, `git`). The auto-detected set is the **union** of every matched profile, so polyglot repos still get what they need; an empty/unknown workspace falls back to `general`. The tool list is locked at session start (don't add/remove servers mid-session — it breaks the prompt cache). The default model pinned by the profiles is `claude-opus-4-8[1m]`; override per-run with `BACK2BASE_MODEL`. Edit or add profiles in [`back2base-container/defaults/profiles.json`](back2base-container/defaults/profiles.json).
 
 ### Adding or removing MCP servers
 

diff --git a/back2base-container/Dockerfile b/back2base-container/Dockerfile
@@ -23,6 +23,10 @@ COPY --chown=node:node skills/ /opt/back2base/defaults/skills/
 # Copy default slash commands. Seeded to ~/.claude/commands/ on first run.
 COPY --chown=node:node commands/ /opt/back2base/defaults/commands/
 
+# Copy default agents bundle (claudekit, MIT). Seeded to ~/.claude/agents/
+# on first run by seed_agents_if_missing.
+COPY --chown=node:node agents/ /opt/back2base/defaults/agents/
+
 # Copy CLAUDE.md template. Assembled into ~/.claude/CLAUDE.md at every
 # container start by generate_claude_md() in entrypoint.sh.
 COPY --chown=node:node defaults/CLAUDE.md.template /opt/back2base/defaults/CLAUDE.md.template
@@ -73,6 +77,11 @@ COPY --chown=node:node --chmod=0755 lib/render-claude-md.py /opt/back2base/rende
 # to decide whether to append a suggestion to pending.md based on edit heuristics.
 COPY --chown=node:node --chmod=0755 lib/claude-md-audit.py /opt/back2base/claude-md-audit.py
 
+# MCP profile auto-detector — run by entrypoint's filter_mcp_by_profile when
+# BACK2BASE_PROFILE is unset. Fingerprints /workspace, prints the resolved
+# MCP server set. Stdlib Python only.
+COPY --chown=node:node --chmod=0755 lib/detect-profile.py /opt/back2base/detect-profile.py
+
 # Pre-launch overview helpers. Sourced by entrypoint.sh between
 # generate_claude_md and the daemon launches when BACK2BASE_OVERVIEW=1.
 COPY --chown=node:node lib/prelaunch-overview.sh /opt/back2base/prelaunch-overview.sh
@@ -99,7 +108,7 @@ COPY --chown=node:node --chmod=0755 lib/power-steering.py /opt/back2base/power-s
 COPY --chown=node:node lib/power-steering-prompt.md /opt/back2base/power-steering-prompt.md
 
 # Belt + suspenders for legacy docker builders that silently ignore --chmod.
-RUN chmod +x /opt/back2base/hooks/_common.sh /opt/back2base/hooks/power-steering-drain.sh /opt/back2base/hooks/power-steering-tick.sh /opt/back2base/hooks/claude-md-audit-tally.sh /opt/back2base/hooks/claude-md-audit-trigger.sh /opt/back2base/session-snapshot.sh /opt/back2base/migrate-settings.py /opt/back2base/render-hooks.py /opt/back2base/firewall-refresh.sh /opt/back2base/path-sentinel.sh /opt/back2base/render-claude-md.py /opt/back2base/claude-md-audit.py /opt/back2base/prelaunch-overview.sh /opt/back2base/render-overview.py /opt/back2base/render-skill-preplan.py /opt/back2base/status.sh /opt/back2base/statusline-extra.sh /opt/back2base/power-steering.py 2>/dev/null || true
+RUN chmod +x /opt/back2base/hooks/_common.sh /opt/back2base/hooks/power-steering-drain.sh /opt/back2base/hooks/power-steering-tick.sh /opt/back2base/hooks/claude-md-audit-tally.sh /opt/back2base/hooks/claude-md-audit-trigger.sh /opt/back2base/session-snapshot.sh /opt/back2base/migrate-settings.py /opt/back2base/render-hooks.py /opt/back2base/firewall-refresh.sh /opt/back2base/path-sentinel.sh /opt/back2base/render-claude-md.py /opt/back2base/claude-md-audit.py /opt/back2base/detect-profile.py /opt/back2base/prelaunch-overview.sh /opt/back2base/render-overview.py /opt/back2base/render-skill-preplan.py /opt/back2base/status.sh /opt/back2base/statusline-extra.sh /opt/back2base/power-steering.py 2>/dev/null || true
 
 # Copy firewall and entrypoint scripts
 COPY init-firewall.sh entrypoint.sh /usr/local/bin/

diff --git a/back2base-container/agents/.gitkeep b/back2base-container/agents/.gitkeep
diff --git a/back2base-container/agents/claudekit/LICENSE b/back2base-container/agents/claudekit/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 claudekit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/back2base-container/agents/claudekit/README.md b/back2base-container/agents/claudekit/README.md
@@ -0,0 +1,100 @@
+# Claudekit Subagents Library
+
+This directory contains specialized subagents for Claude Code that provide deep expertise in specific technical domains.
+
+## Structure
+
+Subagents are organized by domain:
+- `typescript/` - TypeScript and JavaScript experts
+- `react/` - React and frontend framework experts (future)
+- `testing/` - Testing framework experts (future)
+- `database/` - Database and data layer experts (future)
+
+## Format
+
+Each subagent is a markdown file with YAML frontmatter following Claude Code's native format:
+
+```yaml
+---
+name: agent-identifier
+description: Brief description of expertise
+tools: Comma-separated list of allowed tools
+---
+```
+
+## Current Agents
+
+### TypeScript Expert (`typescript/expert.md`)
+- Comprehensive TypeScript and JavaScript expertise
+- Type system mastery
+- Build configuration optimization
+- Module resolution debugging
+- Migration guidance
+
+## Usage
+
+Agents are automatically copied to `.claude/agents/` during `claudekit setup`.
+
+Claude Code will automatically delegate to these agents based on task context.
+
+## Contributing
+
+To add a new subagent:
+1. Create a new `.md` file in the appropriate domain folder
+2. Follow the format requirements above
+3. Add the agent to `cli/commands/setup.ts` agents array
+4. Test the agent with real scenarios
+5. Submit a pull request
+
+## Best Practices
+
+1. **Focused Expertise**: Each agent should have a clear domain
+2. **Comprehensive Prompts**: Include all relevant expertise areas
+3. **Practical Examples**: Provide real commands and patterns
+4. **Tool Restrictions**: Only request necessary tools
+5. **Educational Approach**: Explain while solving
+
+## Agent Authoring Guidelines
+
+### System Prompt Structure
+1. Opening statement defining the agent's role
+2. Core Expertise sections with bullet points
+3. Approach methodology (numbered list)
+4. Key commands and tools section
+5. Common patterns with code examples
+6. Best practices relevant to the domain
+
+### Naming Conventions
+- Use lowercase with hyphens: `typescript-expert`, not `TypeScriptExpert`
+- Be specific but not too narrow: `react-expert` not `react-hooks-expert`
+- Include domain in name when helpful: `typescript-type-expert`
+
+### Tool Selection
+Only request tools the agent actually needs:
+- Read, Grep, Glob - for code analysis
+- Edit, MultiEdit, Write - for code modifications
+- Bash - for running commands
+- WebSearch - only if current information needed
+
+### Testing Your Agent
+1. Install the agent: `claudekit setup`
+2. Open a project in Claude Code
+3. Ask questions relevant to the agent's domain
+4. Verify delegation occurs (Claude mentions using the agent)
+5. Test edge cases and complex scenarios
+
+## Future Agents Roadmap
+
+### Phase 1: Core Domain Experts
+- ✅ typescript-expert - TypeScript/JavaScript
+- ⏳ react-expert - React patterns and hooks
+- ⏳ nodejs-expert - Node.js server patterns
+- ⏳ testing-expert - Testing strategies
+
+### Phase 2: Specialized Experts
+- typescript-type-expert - Advanced type system
+- react-performance-expert - React optimization
+- database-postgres-expert - PostgreSQL
+- docker-expert - Containerization
+
+See the main specification for the complete roadmap.