claudepod 1.1.1 → 1.2.1

package/README.md

@@ -1,244 +1,230 @@
-# ClaudePod
+# ClaudePod DevContainer
 
-A complete development container that sets up Claude Code with 8 powerful MCP servers, modern dev tools, and persistent configurations. Drop it into any project and get a production-ready AI development environment in minutes.
+[![License: GPL-3.0](https://img.shields.io/badge/License-GPL%203.0-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+[![npm version](https://img.shields.io/npm/v/claudepod.svg)](https://www.npmjs.com/package/claudepod)
 
-## What's Inside
+A curated development environment optimized for AI-powered coding with Claude Code. ClaudePod comes pre-configured with language servers, code intelligence tools, and official Anthropic plugins to streamline your development workflow.
 
-**Claude Code CLI** with native binary installation and optimized configuration  
-**8 MCP Servers** providing 100+ specialized tools for code analysis, documentation search, task management, and more  
-**Modern Stack** - Node.js 20, Python 3.13, Git with delta, GitHub CLI  
-**Smart Persistence** - Your Claude config, shell history, and npm cache survive container rebuilds  
-**Enhanced Terminal** - Powerlevel10k with quiet mode and useful git aliases  
+## Installation
 
-## Quick Start
-
-### Using NPM Package
-
-ClaudePod is available as an npm package at [npmjs.com/package/claudepod](https://www.npmjs.com/package/claudepod):
+Add ClaudePod to any project:
 
 ```bash
-# Drop into any project
-cd your-project
-npx claudepod-devcontainer
-
-# Fire it up
-devpod up .
-devpod ssh <workspace-name> --ide vscode  # <workspace-name> is usually your project folder name
-
-# Start coding with Claude
-claude
+npx claudepod
 ```
 
-### Cloning from Repository
-
-```bash
-# Clone the repository
-git clone https://github.com/AnExiledDev/ClaudePod.git
-cd ClaudePod
+This copies the `.devcontainer/` directory to your project. Then open in VS Code and select "Reopen in Container".
 
-# Copy .devcontainer to your project
-cp -r .devcontainer /path/to/your-project/
-cd /path/to/your-project
+## Prerequisites
 
-# Fire it up
-devpod up .
-devpod ssh <workspace-name> --ide vscode  # <workspace-name> is usually your project folder name
+- **Docker Desktop** (or compatible container runtime like Podman)
+- **VS Code** with the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers), or **GitHub Codespaces**
+- **Claude Code authentication** - see [Authentication](#authentication) section
 
-# Start coding with Claude
-claude
-```
-
-That's it. No configuration files to edit, no API keys to hunt down. Everything works out of the box.
+## Quick Start
 
-## The MCP Servers
+1. **Open in Container**
+   - VS Code: Open the folder, then select "Reopen in Container" from the command palette
+   - Codespaces: Create a new codespace from this repository
 
-ClaudePod ships with 8 MCP servers that turn Claude into a powerhouse:
+2. **Authenticate** (first time only)
+   ```bash
+   claude
+   ```
+   Follow the prompts to authenticate via browser or API key.
 
-- **Serena** - Advanced code analysis and semantic search
-- **DeepWiki** - GitHub repository documentation search  
-- **TaskMaster AI** - AI-powered project management
-- **Sequential Thinking** - Structured problem-solving workflows
-- **ccusage** - Claude Code usage analytics and cost tracking
-- **SearXNG Enhanced** - Web search with content scraping
-- **GitHub MCP** - Complete GitHub API integration (API key optional)
-- **Tavily + Ref.Tools** - Web search and documentation tools (API keys optional)
+3. **Start Claude Code**
+   ```bash
+   cc
+   ```
 
-**Tool Permissions**: When Claude first starts, it will ask permission to use these MCP tools. You can deny or allow specific tools based on your needs - this helps manage the large number of available tools (100+). Future versions will make this easier to configure.
+## Authentication
 
-## Requirements
+Claude Code supports multiple authentication methods. On first run, you'll be prompted to choose:
 
-- **[DevPod](https://devpod.sh/)** installed and configured - the container development platform
-- **VS Code** with Remote Development extensions
-- That's literally it
+### Browser Login (Recommended)
 
-## Container Details
+```bash
+claude
+```
 
-**Base**: Ubuntu 22.04  
-**User**: node (1000:1000)  
-**Workspace**: `/workspace` (your project files)  
-**Persistent**: Claude config, shell history, npm cache  
+Select "Login with browser" and complete authentication in your browser. This uses your Claude.ai account.
 
-Your files stay exactly where they are. ClaudePod only adds a `.devcontainer/` directory.
+### API Key
 
-## Handy Commands
+For programmatic access or environments without browsers:
 
 ```bash
-# Claude with statusline and MCP servers
+export ANTHROPIC_API_KEY="sk-ant-..."
 claude
+```
 
-# Git shortcuts (with beautiful diffs)
-gs    # git status
-gd    # git diff
-gc    # git commit
-gp    # git push
-gl    # git log --oneline --graph
+Get an API key from [console.anthropic.com](https://console.anthropic.com/).
 
-# Python without the pain
-uvx <package>     # Run packages without installing
-uv add <package>  # Add dependencies  
+### Credential Persistence
 
-# Quick info
-claudepod_info    # Show status and commands
-```
+Authentication credentials are stored in `/workspaces/.claude/` and persist across container rebuilds.
 
-## Optional Upgrades
+For more options, see the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code).
 
-**Web search is already included** via the built-in SearXNG server - no limits, no API keys required. But you can add more integrations:
+## GitHub CLI Authentication
 
-```bash
-cp .devcontainer/.env.example .devcontainer/.env
-# Edit .devcontainer/.env with your keys
-```
-
-```bash
-# GitHub integration (recommended)
-GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token
+GitHub CLI (`gh`) is pre-installed for repository operations like pushing code, creating pull requests, and accessing private repositories.
 
-# Additional web search via Tavily (optional - SearXNG already provides unlimited search)
-TAVILY_API_KEY=tvly-your-key
+### Interactive Login (Recommended)
 
-# Documentation tools
-REF_TOOLS_API_KEY=your-key
+```bash
+gh auth login
 ```
 
-## Customization & Pitfalls
-
-### The Good News
-ClaudePod is designed to be unbreakable. It uses smart configuration templates that preserve your customizations across container rebuilds.
+Follow the prompts:
+1. Select **GitHub.com** (or your enterprise server)
+2. Choose your preferred protocol: **HTTPS** (recommended) or **SSH**
+3. Authenticate via **browser** (easiest) or paste a personal access token
 
-### Common Gotchas
+### Token-Based Login
 
-**Override Flags** - ClaudePod has environment variables like `OVERRIDE_CLAUDE_SETTINGS=true` that can overwrite your customizations. Only use these if you want to reset to defaults.
+For automated setups or environments without browser access:
 
-**Port Conflicts** - If you run services on ports 8080, 3000, or 5000 locally, add port forwarding rules to avoid conflicts:
+```bash
+# From a file
+gh auth login --with-token < ~/github-token.txt
 
-```json
-{
-  "forwardPorts": [3001, 8081, 5001],
-  "portsAttributes": {
-    "3001": { "label": "Your App" }
-  }
-}
+# From environment variable
+echo "$GITHUB_TOKEN" | gh auth login --with-token
 ```
 
-**Configuration Complexity** - ClaudePod has many layers (devcontainer.json, .env, MCP templates, tool configs). Stick to editing `.devcontainer/.env` for most customizations.
-
-### Safe Customization
-
-Edit `.devcontainer/devcontainer.json` after installation:
-
-```json
-{
-  "containerEnv": {
-    "YOUR_API_KEY": "${localEnv:YOUR_API_KEY}"
-  },
-  "customizations": {
-    "vscode": {
-      "extensions": ["your.extension.id"]
-    }
-  },
-  "features": {
-    "ghcr.io/devcontainers/features/aws-cli:1": {}
-  }
-}
-```
+Generate a token at [github.com/settings/tokens](https://github.com/settings/tokens) with appropriate scopes (typically `repo`, `read:org`).
 
-## Troubleshooting
+### Verifying Authentication
 
-**Container won't start?**
 ```bash
-devpod delete <workspace> && devpod up .  # <workspace> is your project folder name
-# Don't worry - this preserves your ClaudePod configuration and project files
+gh auth status
 ```
 
-**Claude authentication issues?**
-```bash
-claude login
-```
+Expected output shows your authenticated account and token scopes.
+
+### Credential Persistence
+
+GitHub CLI credentials are automatically persisted across container rebuilds. The container is configured to store credentials in `/workspaces/.gh/` (via `GH_CONFIG_DIR`), which is part of the bind-mounted workspace.
+
+**You only need to authenticate once.** After running `gh auth login`, your credentials will survive container rebuilds and be available in future sessions.
+
+## Available Tools
+
+### Languages & Runtimes
+| Tool | Description |
+|------|-------------|
+| Python 3.14 | Base language runtime |
+| Node.js LTS | JavaScript runtime |
+| TypeScript | Via Node.js |
+
+### Package Managers
+| Tool | Description |
+|------|-------------|
+| `uv` | Fast Python package manager (pip alternative) |
+| `npm` | Node.js package manager |
+| `pip` / `pipx` | Python package installers |
+
+### Development Tools
+| Tool | Description |
+|------|-------------|
+| `gh` | GitHub CLI for repository operations |
+| `docker` | Container CLI (connects to host Docker) |
+| `git` | Version control |
+| `jq` | JSON processor |
+| `curl` | HTTP client |
+
+### Code Intelligence
+| Tool | Description |
+|------|-------------|
+| tree-sitter | AST parsing for JavaScript, TypeScript, Python |
+| ast-grep | Structural code search and rewriting |
+| Pyright | Python language server |
+| TypeScript LSP | TypeScript/JavaScript language server |
+
+### Claude Code Tools
+| Tool | Description |
+|------|-------------|
+| `claude` | Claude Code CLI |
+| `cc` | Wrapper with auto-configuration |
+| `ccusage` | Token usage analyzer |
+| `ccstatusline` | Status line for sessions |
+| `claude-monitor` | Real-time usage tracking |
+
+## Using Claude Code
+
+### The `cc` Command
+
+The `cc` command is a wrapper that:
+- Creates a project-local `.claude/` directory if missing
+- Copies default configuration files
+- Launches Claude Code with the project's system prompt
 
-**MCP servers missing?**
 ```bash
-claude mcp list
-# If empty, restart the container
+cc                    # Start Claude Code in current directory
+cc "explain this"     # Start with an initial prompt
 ```
 
-**npm permission errors?**
+### Direct CLI
+
+For more control, use the `claude` command directly:
+
 ```bash
-# Inside container - fix npm permissions
-sudo chown -R node:node /home/node/.npm
-sudo chown -R node:node /home/node/.local
+claude                        # Basic invocation
+claude --help                 # View all options
+claude --resume               # Resume previous session
 ```
 
-**Configuration got overwritten?**
-Look in `.devcontainer/config/backups/` - ClaudePod automatically backs up your configs before making changes.
+## Configuration
 
-## Architecture
+### Environment Variables
 
-ClaudePod uses a two-phase setup:
-1. **post-create.sh** - Installs Claude Code, dev tools, and creates base configurations
-2. **post-start.sh** - Installs MCP servers and validates everything works
+Edit `.devcontainer/.env` to customize behavior:
 
-The setup is idempotent - you can rebuild containers without losing your customizations (unless you use override flags).
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CLAUDE_CONFIG_DIR` | `/workspaces/.claude` | Claude configuration directory |
+| `SETUP_CONFIG` | `true` | Copy config files during setup |
+| `OVERWRITE_CONFIG` | `true` | Overwrite existing configs |
+| `SETUP_ALIASES` | `true` | Add `cc` alias to shell |
+| `SETUP_PLUGINS` | `true` | Install official plugins |
 
-## Team Usage
+### Claude Code Settings
 
-Perfect for teams who want consistent environments:
+Default settings are in `.devcontainer/config/settings.json`. These are copied to `/workspaces/.claude/settings.json` on first run.
 
-```bash
-# Team member 1 sets up the project
-cd shared-project
-npx claudepod-devcontainer
-git add .devcontainer/ && git commit -m "Add ClaudePod"
+Key defaults:
+- **Model**: Claude Opus 4.5
+- **Default mode**: Plan (prompts before executing)
+- **Max output tokens**: 64,000
 
-# Everyone else just runs
-devpod up .
-```
+### System Prompt
 
-Each developer gets an identical environment with the same Claude configuration, MCP servers, and tools.
+The default system prompt is in `.devcontainer/config/main-system-prompt.md`. Override it by creating a `.claude/system-prompt.md` in your project directory.
 
-## What Gets Added
+## Custom Features
 
-```
-your-project/
-├── .devcontainer/
-│   ├── devcontainer.json           # Main container config
-│   ├── post-create.sh             # Tool installation
-│   ├── post-start.sh              # MCP server setup
-│   ├── .env.example               # API key template
-│   ├── config/
-│   │   ├── claude/                # Claude Code templates
-│   │   ├── serena/                # Serena config
-│   │   └── taskmaster/            # TaskMaster config
-│   └── scripts/                   # Modular setup scripts
-└── (your files stay exactly the same)
-```
+ClaudePod includes several custom devcontainer features:
 
-## License
+| Feature | Description |
+|---------|-------------|
+| `claude-monitor` | Real-time token usage monitoring with ML predictions |
+| `ccusage` | Usage analytics CLI |
+| `ccstatusline` | Compact powerline status display |
+| `ast-grep` | Structural code search using AST patterns |
+| `tree-sitter` | Parser with JS/TS/Python grammars |
+| `lsp-servers` | Pyright and TypeScript language servers |
 
-This project is licensed under the GNU General Public License v3.0 (GPL-3.0). See the [full license text](https://www.gnu.org/licenses/gpl-3.0.txt) for details.
+## Essential Gotchas
 
-The GPL-3.0 is a copyleft license that ensures this software remains free and open source, requiring any modifications or derivative works to be released under the same license terms.
+- **Authentication required**: Run `claude` once to authenticate before using `cc`
+- **Plan mode default**: The container starts in "plan" mode, which prompts for approval before making changes
+- **Project-local config**: The `cc` command creates `.claude/` in your current directory for project-specific settings
+- **GitHub auth persists**: Run `gh auth login` once; credentials survive container rebuilds (stored in `/workspaces/.gh/`)
 
----
+## Further Reading
 
-**Ready to code with AI superpowers?** ClaudePod turns any project into an AI-native development environment.
+- [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code)
+- [Dev Containers Specification](https://containers.dev/)
+- [GitHub CLI Manual](https://cli.github.com/manual/)

package/package.json

@@ -1,14 +1,13 @@
 {
   "name": "claudepod",
-  "version": "1.1.1",
-  "description": "Complete development container that sets up Claude Code with 8 powerful MCP servers, modern dev tools, and persistent configurations. Drop it into any project and get a production-ready AI development environment in minutes.",
+  "version": "1.2.1",
+  "description": "Complete development container that sets up Claude Code with modular devcontainer features, modern dev tools, and persistent configurations. Drop it into any project and get a production-ready AI development environment in minutes.",
   "main": "setup.js",
   "bin": {
     "claudepod-devcontainer": "setup.js"
   },
   "scripts": {
-    "test": "node test.js",
-    "validate-mcp": "node .devcontainer/scripts/generate-mcp-config.js"
+    "test": "node test.js"
   },
   "keywords": [
     "devcontainer",
@@ -21,8 +20,8 @@
     "devpod",
     "vscode",
     "container",
-    "serena",
-    "taskmaster",
+    "qdrant",
+    "reasoner",
     "ai-development"
   ],
   "author": "AnExiledDev",
@@ -42,8 +41,5 @@
   "homepage": "https://github.com/AnExiledDev/ClaudePod#readme",
   "bugs": {
     "url": "https://github.com/AnExiledDev/ClaudePod/issues"
-  },
-  "dependencies": {
-    "dotenv": "^17.2.1"
   }
 }

package/setup.js

@@ -56,8 +56,8 @@ function main() {
     console.log('');
     console.log('📚 Features included:');
     console.log('   • Claude Code CLI with optimized tool configuration');
-    console.log('   • MCP servers: Serena, DeepWiki, TaskMaster AI, Sequential Thinking');
-    console.log('   • Development tools: Node.js 20, Python 3.13, Git with delta');
+    console.log('   • MCP servers: Qdrant (vector memory), Reasoner');
+    console.log('   • Development tools: Node.js LTS, Python 3.14, Git with delta');
     console.log('   • Persistent configuration and shell history');
     console.log('');
     console.log('🔗 Documentation: See .devcontainer/README.md');

package/.devcontainer/config/claude/mcp.json

@@ -1,77 +0,0 @@
-{
-  "mcpServers": {
-    "serena": {
-      "command": "uvx",
-      "args": [
-        "--from",
-        "git+https://github.com/oraios/serena",
-        "serena",
-        "start-mcp-server",
-        "--context",
-        "ide-assistant",
-        "--project",
-        "/workspace",
-        "--enable-web-dashboard",
-        "false"
-      ]
-    },
-    "deepwiki": {
-      "type": "http",
-      "url": "https://mcp.deepwiki.com/mcp"
-    },
-    "sequential-thinking": {
-      "command": "uvx",
-      "args": [
-        "--from",
-        "git+https://github.com/arben-adm/mcp-sequential-thinking.git",
-        "--with",
-        "portalocker",
-        "mcp-sequential-thinking"
-      ]
-    },
-    "ccusage": {
-      "command": "ccusage",
-      "args": [
-        "mcp"
-      ]
-    },
-    "searxng-enhanced": {
-      "command": "python3",
-      "args": [
-        "/usr/local/mcp-servers/searxng/mcp_server.py"
-      ],
-      "env": {
-        "ODS_CONFIG_PATH": "/home/node/.claude/ods_config.json",
-        "SEARXNG_ENGINE_API_BASE_URL": "http://localhost:8080/search",
-        "DESIRED_TIMEZONE": "UTC"
-      }
-    },
-    "ref-tools": {
-      "type": "http",
-      "url": "https://api.ref.tools/mcp?apiKey=ref-23a0788cef18edde68af",
-      "env": {
-        "REF_TOOLS_API_KEY": "ref-23a0788cef18edde68af"
-      }
-    },
-    "github": {
-      "command": "docker",
-      "args": [
-        "run",
-        "--rm",
-        "-i",
-        "-e",
-        "GITHUB_PERSONAL_ACCESS_TOKEN=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",
-        "-e",
-        "GITHUB_API_URL=",
-        "-e",
-        "GITHUB_TOOLSET=",
-        "ghcr.io/github/github-mcp-server:latest"
-      ],
-      "env": {
-        "GITHUB_PERSONAL_ACCESS_TOKEN": "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",
-        "GITHUB_API_URL": "",
-        "GITHUB_TOOLSET": ""
-      }
-    }
-  }
-}

package/.devcontainer/config/claude/mcp.json.backup

@@ -1,77 +0,0 @@
-{
-  "mcpServers": {
-    "serena": {
-      "command": "uvx",
-      "args": [
-        "--from",
-        "git+https://github.com/oraios/serena",
-        "serena",
-        "start-mcp-server",
-        "--context",
-        "ide-assistant",
-        "--project",
-        "/workspace",
-        "--enable-web-dashboard",
-        "false"
-      ]
-    },
-    "deepwiki": {
-      "type": "http",
-      "url": "https://mcp.deepwiki.com/mcp"
-    },
-    "sequential-thinking": {
-      "command": "uvx",
-      "args": [
-        "--from",
-        "git+https://github.com/arben-adm/mcp-sequential-thinking.git",
-        "--with",
-        "portalocker",
-        "mcp-sequential-thinking"
-      ]
-    },
-    "ccusage": {
-      "command": "ccusage",
-      "args": [
-        "mcp"
-      ]
-    },
-    "searxng-enhanced": {
-      "command": "python3",
-      "args": [
-        "/usr/local/mcp-servers/searxng/mcp_server.py"
-      ],
-      "env": {
-        "ODS_CONFIG_PATH": "/home/node/.claude/ods_config.json",
-        "SEARXNG_ENGINE_API_BASE_URL": "http://localhost:8080/search",
-        "DESIRED_TIMEZONE": "UTC"
-      }
-    },
-    "ref-tools": {
-      "type": "http",
-      "url": "https://api.ref.tools/mcp?apiKey=ref-23a0788cef18edde68af",
-      "env": {
-        "REF_TOOLS_API_KEY": "ref-23a0788cef18edde68af"
-      }
-    },
-    "github": {
-      "command": "docker",
-      "args": [
-        "run",
-        "--rm",
-        "-i",
-        "-e",
-        "GITHUB_PERSONAL_ACCESS_TOKEN=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",
-        "-e",
-        "GITHUB_API_URL=",
-        "-e",
-        "GITHUB_TOOLSET=",
-        "ghcr.io/github/github-mcp-server:latest"
-      ],
-      "env": {
-        "GITHUB_PERSONAL_ACCESS_TOKEN": "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",
-        "GITHUB_API_URL": "",
-        "GITHUB_TOOLSET": ""
-      }
-    }
-  }
-}