claudepod 1.1.1 → 1.2.1

package/.devcontainer/.env

@@ -0,0 +1,18 @@
+# ClaudePod Environment Configuration
+
+# Paths
+CLAUDE_CONFIG_DIR=/workspaces/.claude
+# CONFIG_SOURCE_DIR is derived from script location; uncomment to override:
+# CONFIG_SOURCE_DIR=/custom/path/to/config
+
+# Setup: copy config files to CLAUDE_CONFIG_DIR
+SETUP_CONFIG=true
+
+# Setup: overwrite existing config files (false = skip if exists)
+OVERWRITE_CONFIG=true
+
+# Setup: add cc alias to shell rc files
+SETUP_ALIASES=true
+
+# Setup: install official Anthropic plugins
+SETUP_PLUGINS=true

package/.devcontainer/CHANGELOG.md

@@ -0,0 +1,68 @@
+# ClaudePod Devcontainer Changelog
+
+## [2025-01-19] Documentation & GitHub CLI Persistence
+
+### Added
+- **README.md**: Comprehensive documentation including:
+  - Prerequisites and quick start guide
+  - GitHub CLI authentication instructions (interactive and token-based)
+  - Available tools reference tables
+  - Configuration guide
+  - Essential gotchas
+- **CLAUDE.md**: Development guide for Claude Code with:
+  - Directory structure overview
+  - Key configuration files reference
+  - Command reference
+  - Feature development guide
+  - Setup scripts documentation
+- **GitHub CLI Credential Persistence**: Added `GH_CONFIG_DIR=/workspaces/.gh` to `remoteEnv` so credentials survive container rebuilds
+
+### Files Created
+- `/workspaces/.devcontainer/README.md`
+- `/workspaces/.devcontainer/CLAUDE.md`
+
+### Files Modified
+- `/workspaces/.devcontainer/devcontainer.json` - Added `GH_CONFIG_DIR` environment variable
+
+---
+
+## [2025-01-19] Configuration Updates
+
+### Added
+- **GitHub CLI**: Added `ghcr.io/devcontainers/features/github-cli:1` feature for GitHub operations
+- **Official Anthropic Plugins**: New `setup-plugins.sh` script installs 7 official plugins:
+  - `@anthropics/claude-plugins-official/frontend-design`
+  - `@anthropics/claude-plugins-official/code-review`
+  - `@anthropics/claude-plugins-official/commit-commands`
+  - `@anthropics/claude-plugins-official/pr-review-toolkit`
+  - `@anthropics/claude-plugins-official/typescript-lsp`
+  - `@anthropics/claude-plugins-official/pyright-lsp`
+  - `@anthropics/claude-plugins-official/code-simplifier`
+- **SETUP_PLUGINS** environment variable to control plugin installation
+
+### Changed
+- **Plan Mode Default**: Changed `defaultMode` from `"dontAsk"` to `"plan"` in settings.json
+- **cc Command**: Replaced simple alias with smart function that:
+  - Checks for `.claude/system-prompt.md` in current directory
+  - Auto-creates from `/workspaces/.devcontainer/config/main-system-prompt.md` if missing
+  - Enables per-project system prompt customization
+
+### Removed
+- **Specwright**: Completely removed (setup script, aliases, plugin files, ORCHESTRATOR.md)
+
+### Files Modified
+- `/workspaces/.devcontainer/devcontainer.json` - Added GitHub CLI feature
+- `/workspaces/.devcontainer/config/settings.json` - Set defaultMode to plan
+- `/workspaces/.devcontainer/scripts/setup-aliases.sh` - Replaced cc alias with function
+- `/workspaces/.devcontainer/.env` - Removed specwright, added plugins
+- `/workspaces/.devcontainer/scripts/setup.sh` - Removed specwright, added setup-plugins.sh
+
+### Files Deleted
+- `/workspaces/.devcontainer/scripts/setup-specwright.sh`
+- `/workspaces/.claude/ORCHESTRATOR.md`
+- `/workspaces/.claude/plugins/marketplaces/specwright-marketplace/`
+- `/workspaces/.claude/plugins/cache/specwright-marketplace/`
+
+### Files Created
+- `/workspaces/.devcontainer/scripts/setup-plugins.sh` - Plugin installer script
+- `/workspaces/.devcontainer/CHANGELOG.md` - This changelog

package/.devcontainer/CLAUDE.md

@@ -0,0 +1,100 @@
+# DevContainer Development Guide
+
+ClaudePod devcontainer for AI-assisted development with Claude Code.
+
+## Directory Structure
+
+```
+/workspaces/
+├── .devcontainer/           # Container configuration (this directory)
+│   ├── devcontainer.json    # Main container definition
+│   ├── .env                 # Environment variables
+│   ├── config/              # Default configurations
+│   │   ├── settings.json    # Claude Code settings
+│   │   └── main-system-prompt.md
+│   ├── features/            # Custom devcontainer features
+│   └── scripts/             # Setup scripts
+├── .claude/                 # Runtime Claude config (created on first run)
+│   ├── settings.json        # Active settings
+│   └── system-prompt.md     # Active system prompt
+└── .gh/                     # GitHub CLI config (persists across rebuilds)
+    └── hosts.yml            # Authenticated hosts
+```
+
+## Key Configuration Files
+
+| File | Purpose |
+|------|---------|
+| `devcontainer.json` | Container definition: base image, features, mounts, environment |
+| `.env` | Environment variables controlling setup behavior |
+| `config/settings.json` | Claude Code defaults: model, tokens, permissions, plugins |
+| `config/main-system-prompt.md` | Default system prompt defining assistant behavior |
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `cc` | Run Claude Code with auto-configuration (creates local `.claude/` if needed) |
+| `claude` | Direct Claude Code CLI |
+| `ccusage` | Analyze token usage history |
+| `gh` | GitHub CLI for repo operations |
+| `uv` | Fast Python package manager |
+| `ast-grep` | Structural code search |
+
+## Feature Development
+
+Custom features live in `./features/`. Each feature follows the [devcontainer feature spec](https://containers.dev/implementors/features/):
+
+```
+features/
+└── my-feature/
+    ├── devcontainer-feature.json   # Metadata and options
+    ├── install.sh                  # Installation script
+    └── README.md                   # Documentation
+```
+
+To test a feature locally, reference it in `devcontainer.json`:
+```json
+"features": {
+  "./features/my-feature": {}
+}
+```
+
+## Setup Scripts
+
+Scripts in `./scripts/` run via `postStartCommand`:
+
+| Script | Purpose |
+|--------|---------|
+| `setup.sh` | Main orchestrator |
+| `setup-config.sh` | Copies config files to `/workspaces/.claude/` |
+| `setup-aliases.sh` | Creates `cc` shell function |
+| `setup-lsp.sh` | Installs LSP plugins |
+| `setup-plugins.sh` | Installs official Anthropic plugins |
+
+## Installed Plugins
+
+Automatically installed on container start:
+
+- `frontend-design@claude-plugins-official`
+- `code-review@claude-plugins-official`
+- `commit-commands@claude-plugins-official`
+- `pr-review-toolkit@claude-plugins-official`
+
+## Environment Variables
+
+Key environment variables set in the container:
+
+| Variable | Value |
+|----------|-------|
+| `WORKSPACE_ROOT` | `/workspaces` |
+| `CLAUDE_CONFIG_DIR` | `/workspaces/.claude` |
+| `GH_CONFIG_DIR` | `/workspaces/.gh` |
+| `ANTHROPIC_MODEL` | `claude-opus-4-5-20251101` |
+
+## Modifying Behavior
+
+1. **Change default model**: Edit `config/settings.json`, update `"model"` field
+2. **Change system prompt**: Edit `config/main-system-prompt.md`
+3. **Add features**: Add to `"features"` in `devcontainer.json`
+4. **Disable auto-setup**: Set variables to `false` in `.env`

package/.devcontainer/README.md

@@ -0,0 +1,220 @@
+# ClaudePod DevContainer
+
+[![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)
+
+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.
+
+## Prerequisites
+
+- **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
+
+## Quick Start
+
+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
+
+2. **Authenticate** (first time only)
+   ```bash
+   claude
+   ```
+   Follow the prompts to authenticate via browser or API key.
+
+3. **Start Claude Code**
+   ```bash
+   cc
+   ```
+
+## Authentication
+
+Claude Code supports multiple authentication methods. On first run, you'll be prompted to choose:
+
+### Browser Login (Recommended)
+
+```bash
+claude
+```
+
+Select "Login with browser" and complete authentication in your browser. This uses your Claude.ai account.
+
+### API Key
+
+For programmatic access or environments without browsers:
+
+```bash
+export ANTHROPIC_API_KEY="sk-ant-..."
+claude
+```
+
+Get an API key from [console.anthropic.com](https://console.anthropic.com/).
+
+### Credential Persistence
+
+Authentication credentials are stored in `/workspaces/.claude/` and persist across container rebuilds.
+
+For more options, see the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code).
+
+## GitHub CLI Authentication
+
+GitHub CLI (`gh`) is pre-installed for repository operations like pushing code, creating pull requests, and accessing private repositories.
+
+### Interactive Login (Recommended)
+
+```bash
+gh auth login
+```
+
+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
+
+### Token-Based Login
+
+For automated setups or environments without browser access:
+
+```bash
+# From a file
+gh auth login --with-token < ~/github-token.txt
+
+# From environment variable
+echo "$GITHUB_TOKEN" | gh auth login --with-token
+```
+
+Generate a token at [github.com/settings/tokens](https://github.com/settings/tokens) with appropriate scopes (typically `repo`, `read:org`).
+
+### Verifying Authentication
+
+```bash
+gh auth status
+```
+
+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
+
+```bash
+cc                    # Start Claude Code in current directory
+cc "explain this"     # Start with an initial prompt
+```
+
+### Direct CLI
+
+For more control, use the `claude` command directly:
+
+```bash
+claude                        # Basic invocation
+claude --help                 # View all options
+claude --resume               # Resume previous session
+```
+
+## Configuration
+
+### Environment Variables
+
+Edit `.devcontainer/.env` to customize behavior:
+
+| 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 |
+
+### Claude Code Settings
+
+Default settings are in `.devcontainer/config/settings.json`. These are copied to `/workspaces/.claude/settings.json` on first run.
+
+Key defaults:
+- **Model**: Claude Opus 4.5
+- **Default mode**: Plan (prompts before executing)
+- **Max output tokens**: 64,000
+
+### System Prompt
+
+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.
+
+## Custom Features
+
+ClaudePod includes several custom devcontainer features:
+
+| 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 |
+
+## Essential Gotchas
+
+- **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
+
+- [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/.devcontainer/config/main-system-prompt.md

@@ -0,0 +1,118 @@
+<identity>
+You are Alira.
+</identity>
+
+<response_guidelines>
+Begin responses with substantive content.
+
+Match emoji usage to source material or explicit requests.
+
+Mark uncertainty explicitly. Distinguish confirmed facts from inference.
+
+<example>
+User: "What's the best sorting algorithm?"
+Alira: "Context determines the answer. For nearly-sorted data, insertion sort excels. For general-purpose use with guaranteed O(n log n), merge sort or heapsort. What's your use case?"
+</example>
+</response_guidelines>
+
+<core_directives>
+Execute rigorously. Pass to all subagents. Deviation requires explicit user approval.
+
+Write minimal code that satisfies requirements.
+
+Address concrete problems present in the codebase.
+
+When theory conflicts with working solutions, follow working solutions.
+
+Data structures and their relationships are the foundation; code follows from them.
+
+The right abstraction handles all cases uniformly.
+
+<orchestration>
+Main thread: orchestration and code modification only.
+
+Subagents handle all information gathering—file reading, searches, context assembly, dependency analysis, test execution. Subagents report; main thread synthesizes, decides, acts.
+
+<example>
+User: "Update the authentication module to use JWT"
+Alira: Spawns subagent to gather current auth implementation, token handling, test coverage. Receives findings. Main thread plans and executes modifications.
+</example>
+</orchestration>
+
+<task_handling>
+Present task interpretation and await approval before work begins.
+
+When uncertain, deploy subagent to gather clarifying context. Ask user only when ambiguity persists after subagent findings.
+
+Present plans, await approval. Execute directly only when explicitly instructed or trivially simple.
+
+<example>
+User: "Refactor the data layer"
+Alira: "Interpretation: restructure repository pattern in /src/data/ to reduce coupling between models and persistence logic. Scope: UserRepository, OrderRepository, shared base class. Tests updated to match. Proceed?"
+</example>
+</task_handling>
+
+<context_overflow>
+When context nears capacity: stop. State remaining capacity and work status. Wait for user direction.
+</context_overflow>
+</core_directives>
+
+<code_directives>
+Python: 2-3 nesting levels. Other languages: 3-4 levels. Extract functions beyond these thresholds.
+
+Functions: short, single purpose.
+
+Handle errors at appropriate boundaries with general patterns.
+
+Special cases signal architectural gaps. Redesign for uniform handling.
+
+Optimize performance with measured evidence of user impact. Prefer simple code over marginal speed gains.
+
+Verify changes preserve existing functionality. Document issues exceeding context limits and request guidance.
+
+<documentation>
+Inline comments explain *why*, only when non-obvious. Routine documentation belongs in docblocks: purpose, parameters, return values, usage.
+
+<example>
+# why (correct)
+offset = len(header) + 1  # null terminator in legacy format
+
+# what (unnecessary)
+
+offset = len(header) + 1 # add one to header length
+</example>
+</documentation>
+
+<code_standards>
+Files: small, focused, single purpose. One reason to change per file.
+
+<solid>
+Single Responsibility: each module, class, function owns one concern.
+
+Open/Closed: extend behavior through composition and abstraction; existing code remains stable.
+
+Liskov Substitution: subtypes fulfill the contracts of their parents completely.
+
+Interface Segregation: small, specific interfaces. Clients depend only on methods they use.
+
+Dependency Inversion: depend on abstractions. High-level modules and low-level modules both point toward interfaces.
+</solid>
+
+<principles>
+DRY: single source of truth for knowledge and logic. Extract, reference, reuse.
+
+KISS: favor straightforward solutions. Complexity requires justification.
+
+YAGNI: implement for current requirements. Speculative features wait until needed.
+
+Convention over Configuration: follow established patterns; configure only where deviation is necessary.
+
+Law of Demeter: objects interact with immediate collaborators. Avoid reaching through chains.
+</principles>
+
+<example>
+User: "Add email notifications when orders ship"
+Alira: Creates NotificationService interface, EmailNotifier implementation, injects into OrderService. OrderService calls notifier.send()—unaware of email specifics. One file per component.
+</example>
+</code_standards>
+</code_directives>

package/.devcontainer/config/settings.json

@@ -0,0 +1,41 @@
+{
+  "cleanupPeriodDays": 360,
+  "env": {
+    "ANTHROPIC_MODEL": "claude-opus-4-5-20251101",
+    "CLAUDE_CODE_SUBAGENT_MODEL": "claude-opus-4-5-20251101",
+    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-5-20251101",
+    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-5-20250929",
+    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5-20251001",
+    "BASH_DEFAULT_TIMEOUT_MS": "240000",
+    "BASH_MAX_TIMEOUT_MS": "600000",
+    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "true",
+    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "64000",
+    "MAX_MCP_OUTPUT_TOKENS": "10000",
+    "MAX_THINKING_TOKENS": "14999",
+    "MCP_TIMEOUT": "120000",
+    "MCP_TOOL_TIMEOUT": "30000"
+  },
+  "includeCoAuthoredBy": false,
+  "permissions": {
+    "allow": [
+      "Read(/workspaces/*)",
+      "WebFetch(domain:*)"
+    ],
+    "deny": [],
+    "ask": [],
+    "defaultMode": "plan",
+    "additionalDirectories": []
+  },
+  "model": "opus",
+  "enabledMcpjsonServers": [],
+  "disabledMcpjsonServers": [],
+  "hooks": {},
+  "statusLine": {
+    "type": "command",
+    "command": "/usr/local/bin/ccstatusline-wrapper"
+  },
+  "enabledPlugins": {
+    "frontend-design@claude-code-plugins": true
+  },
+  "outputStyle": ""
+}