vibepod 0.1.0__tar.gz

vibepod-0.1.0/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: vibepod
+Version: 0.1.0
+Summary: One CLI for containerized AI coding agents
+Author: VibePod
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: docker>=7.0.0
+Requires-Dist: platformdirs>=4.0.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# VibePod
+
+VibePod is a unified CLI (`vp`) for running AI coding agents in Docker containers.
+
+## Current Status
+
+This repository contains an initial v1 implementation with:
+
+- `vp run <agent>`
+- `vp stop <agent|--all>`
+- `vp list`
+- `vp logs ui`
+- `vp config show`
+- `vp config path`
+- `vp version`
+
+## Image Namespace
+
+By default, agent images use the `nezhar` namespace (for example `nezhar/claude-container:latest`).
+
+
+Current defaults are aligned to existing container repos:
+
+- `claude` -> `nezhar/claude-container:latest` ([repo](https://github.com/nezhar/claude-container))
+- `gemini` -> `nezhar/gemini-container:latest` ([repo](https://github.com/nezhar/gemini-container))
+- `opencode` -> `nezhar/opencode-cli:latest` ([repo](https://github.com/nezhar/opencode-container))
+- `devstral` -> `nezhar/devstral-cli:latest` ([repo](https://github.com/nezhar/devstral-container))
+- `auggie` -> `nezhar/auggie-cli:latest` ([repo](https://github.com/nezhar/auggie-container))
+- `copilot` -> `nezhar/copilot-cli:latest` ([repo](https://github.com/nezhar/copilot-container))
+- `codex` -> `nezhar/codex-cli:latest` ([repo](https://github.com/nezhar/codex-container))
+
+You can override any single image directly:
+
+```bash
+VP_IMAGE_CLAUDE=nezhar/claude-container:latest vp run claude
+VP_IMAGE_GEMINI=nezhar/gemini-container:latest vp run gemini
+VP_IMAGE_OPENCODE=nezhar/opencode-cli:latest vp run opencode
+VP_IMAGE_DEVSTRAL=nezhar/devstral-cli:latest vp run devstral
+VP_IMAGE_AUGGIE=nezhar/auggie-cli:latest vp run auggie
+VP_IMAGE_COPILOT=nezhar/copilot-cli:latest vp run copilot
+VP_IMAGE_CODEX=nezhar/codex-cli:latest vp run codex
+VP_DATASETTE_IMAGE=nezhar/opencode-datasette:latest vp logs ui
+```

vibepod-0.1.0/PLAN.md

@@ -0,0 +1,189 @@
+# VibePod Implementation Plan
+
+## Objective
+
+Build a practical v1 of `vp` that unifies running agent CLIs in Docker with a consistent interface, while keeping the initial scope small and reliable.
+
+## Guiding Principles
+
+- Ship a thin, stable core before broad feature coverage.
+- Keep agent-specific behavior behind adapters.
+- Prefer clear UX and predictable defaults over cleverness.
+- Make all state locations explicit and inspectable.
+
+## v1 Scope
+
+### In Scope
+
+- Project scaffold (`pyproject.toml`, `src/`, `tests/`, basic tooling).
+- Core commands:
+  - `vp run <agent>`
+  - `vp stop <agent|--all>`
+  - `vp list`
+  - `vp logs ui`
+  - `vp config show`
+  - `vp config path`
+  - `vp version`
+- Supported agents in registry: `claude`, `gemini`, `opencode`, `devstral`, `auggie`.
+- Docker lifecycle management via Docker SDK (no shelling out to docker CLI).
+- Config loading/merging: defaults + global + project + env overrides.
+- Container labels and naming conventions for reliable discovery.
+
+### Out of Scope (Post-v1)
+
+- Full `vp auth` flows.
+- Full `vp skills` integration and MCP management.
+- `vp logs query/export/stats`.
+- Auto-update command, installers, and release automation.
+
+## Architecture Decisions
+
+### 1) Agent Adapter Contract
+
+Each agent implements a small adapter interface:
+
+- `image(config) -> str`
+- `config_mounts(paths) -> list[MountSpec]`
+- `env(config, runtime) -> dict[str, str]`
+- `command(runtime) -> list[str]`
+- `healthcheck(container) -> AdapterStatus`
+
+This keeps `run/stop/list` generic and avoids hardcoding agent quirks.
+
+### 2) Container Identity
+
+Use both predictable names and labels:
+
+- Name: `vibepod-{agent}-{shortid}`
+- Labels:
+  - `vibepod.managed=true`
+  - `vibepod.agent=<agent>`
+  - `vibepod.workspace=<absolute-path>`
+  - `vibepod.version=<vp-version>`
+
+All operational commands (`list`, `stop`, future logs) discover containers via labels.
+
+### 3) Config Paths
+
+- Global config dir: `~/.config/vibepod` (platformdirs-backed)
+- Global file: `~/.config/vibepod/config.yaml`
+- Project file: `.vibepod/config.yaml`
+- Env prefix: `VP_`
+
+Precedence: env > project > global > defaults.
+
+## Milestones
+
+## M0 - Repository Bootstrap
+
+Deliverables:
+
+- `pyproject.toml` with runtime + dev dependencies.
+- Source layout under `src/vibepod`.
+- Test scaffold (`pytest`, basic CLI smoke tests).
+- Lint/format/type config (`ruff`, `mypy`).
+
+Acceptance Criteria:
+
+- `vp --help` runs locally.
+- `pytest` runs with at least one passing smoke test.
+- `ruff check` and `ruff format --check` pass.
+
+## M1 - Core Domain Layer
+
+Deliverables:
+
+- `constants.py` for defaults and agent metadata.
+- `core/config.py` with merge logic and env overrides.
+- `core/agents.py` with adapter registry and validation.
+- `core/docker.py` wrapper for Docker SDK interactions.
+
+Acceptance Criteria:
+
+- Unit tests for config merge precedence.
+- Agent lookup validates known/unknown agents.
+- Docker wrapper can detect daemon availability.
+
+## M2 - Command MVP
+
+Deliverables:
+
+- `vp run`, `vp stop`, `vp list`, `vp version`.
+- Common output helpers with Rich.
+- Error-to-exit-code mapping.
+
+Acceptance Criteria:
+
+- `vp run claude` starts a managed container (when Docker daemon available).
+- `vp list` shows running managed containers with agent + workspace.
+- `vp stop claude` stops the correct container.
+- `vp stop --all` stops all managed containers only.
+
+## M3 - Logging UI + Config UX
+
+Deliverables:
+
+- `vp logs ui` starts/reuses Datasette container.
+- `vp config show` and `vp config path`.
+- Config directory first-run setup.
+
+Acceptance Criteria:
+
+- `vp logs ui` launches Datasette bound to configured port.
+- `vp config show` displays effective merged config.
+- `vp config path` prints global/project paths consistently across OS.
+
+## M4 - Hardening + Docs
+
+Deliverables:
+
+- Robust error messages and troubleshooting hints.
+- README aligned with actual v1 capabilities.
+- Basic manual test checklist.
+
+Acceptance Criteria:
+
+- Clear errors for Docker unavailable, image missing, invalid agent.
+- End-to-end smoke tests documented and reproducible.
+
+## Work Breakdown (File-by-File)
+
+1. `pyproject.toml`
+2. `src/vibepod/__init__.py`
+3. `src/vibepod/constants.py`
+4. `src/vibepod/core/config.py`
+5. `src/vibepod/core/agents.py`
+6. `src/vibepod/core/docker.py`
+7. `src/vibepod/utils/console.py`
+8. `src/vibepod/commands/run.py`
+9. `src/vibepod/commands/stop.py`
+10. `src/vibepod/commands/list.py`
+11. `src/vibepod/commands/logs.py`
+12. `src/vibepod/commands/config.py`
+13. `src/vibepod/commands/update.py` (version command only for v1)
+14. `src/vibepod/cli.py`
+15. `tests/test_cli.py`
+16. `tests/test_config.py`
+17. `tests/test_agents.py`
+
+## Risks and Mitigations
+
+- Docker SDK behavior differences by platform
+  - Mitigation: keep a thin wrapper and centralize exception handling.
+- Agent image runtime differences
+  - Mitigation: adapter interface + per-agent env/mount defaults.
+- Config drift as features expand
+  - Mitigation: keep schema versioning and add migration hooks early.
+- Logs may contain sensitive content
+  - Mitigation: default body logging off; document explicitly.
+
+## Definition of Done (v1)
+
+- All in-scope commands implemented and documented.
+- Unit tests cover config merge + command routing + agent validation.
+- Manual smoke test passes on Linux/macOS with Docker Desktop/Engine.
+- README reflects only implemented behavior.
+
+## Immediate Next Step
+
+Start M0 by scaffolding the package and wiring a minimal Typer app that exposes `vp --help` and `vp version`.

vibepod-0.1.0/README.md

@@ -0,0 +1,43 @@
+# VibePod
+
+VibePod is a unified CLI (`vp`) for running AI coding agents in Docker containers.
+
+## Current Status
+
+This repository contains an initial v1 implementation with:
+
+- `vp run <agent>`
+- `vp stop <agent|--all>`
+- `vp list`
+- `vp logs ui`
+- `vp config show`
+- `vp config path`
+- `vp version`
+
+## Image Namespace
+
+By default, agent images use the `nezhar` namespace (for example `nezhar/claude-container:latest`).
+
+
+Current defaults are aligned to existing container repos:
+
+- `claude` -> `nezhar/claude-container:latest` ([repo](https://github.com/nezhar/claude-container))
+- `gemini` -> `nezhar/gemini-container:latest` ([repo](https://github.com/nezhar/gemini-container))
+- `opencode` -> `nezhar/opencode-cli:latest` ([repo](https://github.com/nezhar/opencode-container))
+- `devstral` -> `nezhar/devstral-cli:latest` ([repo](https://github.com/nezhar/devstral-container))
+- `auggie` -> `nezhar/auggie-cli:latest` ([repo](https://github.com/nezhar/auggie-container))
+- `copilot` -> `nezhar/copilot-cli:latest` ([repo](https://github.com/nezhar/copilot-container))
+- `codex` -> `nezhar/codex-cli:latest` ([repo](https://github.com/nezhar/codex-container))
+
+You can override any single image directly:
+
+```bash
+VP_IMAGE_CLAUDE=nezhar/claude-container:latest vp run claude
+VP_IMAGE_GEMINI=nezhar/gemini-container:latest vp run gemini
+VP_IMAGE_OPENCODE=nezhar/opencode-cli:latest vp run opencode
+VP_IMAGE_DEVSTRAL=nezhar/devstral-cli:latest vp run devstral
+VP_IMAGE_AUGGIE=nezhar/auggie-cli:latest vp run auggie
+VP_IMAGE_COPILOT=nezhar/copilot-cli:latest vp run copilot
+VP_IMAGE_CODEX=nezhar/codex-cli:latest vp run codex
+VP_DATASETTE_IMAGE=nezhar/opencode-datasette:latest vp logs ui
+```

vibepod-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "vibepod"
+version = "0.1.0"
+description = "One CLI for containerized AI coding agents"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "VibePod" }]
+dependencies = [
+    "typer>=0.12.0",
+    "rich>=13.0.0",
+    "docker>=7.0.0",
+    "pyyaml>=6.0.0",
+    "platformdirs>=4.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "ruff>=0.6.0",
+    "mypy>=1.11.0",
+]
+
+[project.scripts]
+vp = "vibepod.cli:app"
+vibepod = "vibepod.cli:app"
+
+[build-system]
+requires = ["hatchling>=1.24.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build]
+exclude = ["venv", "venv/**"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vibepod"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "UP", "B"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = true
+warn_unused_ignores = true

vibepod-0.1.0/specs/00-INDEX.md

@@ -0,0 +1,202 @@
+# VibePod Specification Index
+
+**Project:** VibePod  
+**Domain:** vibepod.dev  
+**CLI:** `vp`  
+**Version:** 1.0.0  
+
+---
+
+## Document Index
+
+| # | Document | Description |
+|---|----------|-------------|
+| 01 | [OVERVIEW.md](01-OVERVIEW.md) | Project overview, goals, architecture |
+| 02 | [CLI-COMMANDS.md](02-CLI-COMMANDS.md) | Complete CLI reference |
+| 03 | [PROJECT-STRUCTURE.md](03-PROJECT-STRUCTURE.md) | Python project structure, pyproject.toml |
+| 04 | [CONFIGURATION.md](04-CONFIGURATION.md) | Config files, schema, management |
+| 05 | [DOCKER-INTEGRATION.md](05-DOCKER-INTEGRATION.md) | Docker SDK, containers, volumes |
+| 06 | [LOGGING-DATASETTE.md](06-LOGGING-DATASETTE.md) | SQLite logging, Datasette UI |
+| 07 | [CICD-WORKFLOWS.md](07-CICD-WORKFLOWS.md) | GitHub Actions, releases |
+| 08 | [INSTALLATION.md](08-INSTALLATION.md) | Install scripts, Homebrew |
+| 09 | [README.md](09-README.md) | Repository README template |
+
+---
+
+## Quick Reference
+
+### Brand Assets
+
+| Asset | Value |
+|-------|-------|
+| Domain | vibepod.dev |
+| GitHub Org | github.com/VibePod |
+| Docker Hub | hub.docker.com/u/vibepod |
+| X/Twitter | @vibepod_dev |
+| Discord | (server created) |
+
+### Repositories
+
+| Repository | Purpose |
+|------------|---------|
+| `VibePod/vibepod` | Main CLI (Python/Typer) |
+| `VibePod/docs` | Documentation site |
+| `VibePod/skills` | Official skills |
+| `nezhar/claude-container` | → `vibepod/claude` |
+| `nezhar/gemini-container` | → `vibepod/gemini` |
+| `nezhar/opencode-container` | → `vibepod/opencode` |
+| `nezhar/devstral-container` | → `vibepod/devstral` |
+| `nezhar/auggie-container` | → `vibepod/auggie` |
+
+### Tech Stack
+
+| Component | Technology |
+|-----------|------------|
+| Language | Python 3.10+ |
+| CLI Framework | Typer |
+| Docker | docker-py SDK |
+| Config | YAML (PyYAML) |
+| Output | Rich |
+| Skills | AGENTS.lock |
+| Logging | SQLite + Datasette |
+| CI/CD | GitHub Actions |
+| Package | PyPI + PyInstaller binaries |
+
+### Docker Images
+
+```
+vibepod/claude
+vibepod/gemini
+vibepod/opencode
+vibepod/devstral
+vibepod/auggie
+vibepod/datasette
+```
+
+### Core Commands
+
+```bash
+vp run <agent>       # Start agent
+vp stop --all        # Stop all
+vp list              # List agents
+vp logs ui           # Datasette
+vp skills sync       # AGENTS.lock
+vp config show       # Configuration
+```
+
+### Aliases
+
+```bash
+vp c    # → vp run claude
+vp g    # → vp run gemini
+vp o    # → vp run opencode
+vp d    # → vp run devstral
+vp a    # → vp run auggie
+vp ui   # → vp logs ui
+```
+
+---
+
+## Implementation Checklist
+
+### Phase 1: Core CLI
+
+- [ ] Project setup (pyproject.toml, structure)
+- [ ] Basic CLI with Typer
+- [ ] `vp run` command
+- [ ] `vp stop` command
+- [ ] `vp list` command
+- [ ] Docker integration
+- [ ] Configuration loading
+- [ ] Aliases support
+
+### Phase 2: Skills & Logging
+
+- [ ] AGENTS.lock integration (`vp skills`)
+- [ ] SQLite logging
+- [ ] Datasette container (`vp logs ui`)
+- [ ] `vp logs stats` command
+
+### Phase 3: Polish
+
+- [ ] `vp auth` commands
+- [ ] Shell completions
+- [ ] Error handling
+- [ ] Tests
+- [ ] Documentation
+
+### Phase 4: Release
+
+- [ ] GitHub Actions workflows
+- [ ] PyPI publishing
+- [ ] Binary builds
+- [ ] Install scripts
+- [ ] Homebrew formula
+- [ ] vibepod.dev website
+
+---
+
+## Development Commands
+
+```bash
+# Setup
+git clone https://github.com/VibePod/vibepod
+cd vibepod
+pip install -e ".[dev]"
+
+# Development
+pytest                    # Run tests
+ruff check src tests      # Lint
+ruff format src tests     # Format
+mypy src                  # Type check
+
+# Build
+python -m build           # Build package
+pyinstaller ...           # Build binary
+
+# Release
+git tag v1.0.0
+git push --tags           # Triggers CI release
+```
+
+---
+
+## External Dependencies
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| typer | >=0.12.0 | CLI framework |
+| docker | >=7.0.0 | Docker SDK |
+| pyyaml | >=6.0 | Config parsing |
+| rich | >=13.0 | Terminal output |
+| platformdirs | >=4.0 | Cross-platform paths |
+| agentslock | >=0.1.0 | AGENTS.lock integration |
+| httpx | >=0.27.0 | HTTP client |
+
+---
+
+## Notes for Claude Code
+
+When building VibePod:
+
+1. **Start with project structure** - Create pyproject.toml and directory layout first
+2. **Build incrementally** - Get `vp run claude` working before adding other features
+3. **Test Docker early** - Ensure Docker SDK works before building commands
+4. **Use the specs** - Reference these documents for implementation details
+5. **Keep it simple** - Python readability over performance
+
+The specs are designed to be self-contained. Each document has enough detail to implement that component.
+
+---
+
+## Questions?
+
+If anything is unclear in these specs, the intent is:
+
+- **Simple over complex** - Choose the straightforward solution
+- **Python conventions** - Follow standard Python patterns
+- **Docker SDK** - Use docker-py, not subprocess
+- **Typer patterns** - Follow Typer's recommended CLI structure
+- **YAML config** - Simple, readable configuration
+
+Good luck building VibePod! 🎵

vibepod-0.1.0/specs/01-OVERVIEW.md

@@ -0,0 +1,157 @@
+# VibePod Specification
+
+**Version:** 1.0.0  
+**Date:** February 2026  
+**Language:** Python 3.10+  
+**CLI Framework:** Typer  
+
+---
+
+## Project Overview
+
+VibePod is a unified CLI tool for running AI coding agents in isolated Docker containers.
+
+### Goals
+
+1. **Unified interface** - One CLI (`vp`) for all agents
+2. **Container isolation** - Each agent runs in Docker
+3. **Skills management** - Via AGENTS.lock integration
+4. **API logging** - Datasette-powered analytics
+5. **Cross-platform** - macOS, Linux, Windows
+
+### Non-Goals
+
+- Building the container images (handled by nezhar/*-container repos)
+- Replacing AGENTS.lock (we integrate, not reimplement)
+- Performance optimization (readability over speed)
+
+---
+
+## Brand Assets
+
+| Platform | Namespace | Status |
+|----------|-----------|--------|
+| Domain | vibepod.dev | ✅ |
+| GitHub | github.com/VibePod | ✅ |
+| Docker Hub | hub.docker.com/u/vibepod | ✅ |
+| X/Twitter | @vibepod_dev | ✅ |
+| Discord | VibePod server | ✅ |
+| Bluesky | @vibepod.dev (via DNS) | 🔒 |
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        User                                      │
+│                          │                                       │
+│                          ▼                                       │
+│                    ┌───────────┐                                │
+│                    │  vp CLI   │  (Python/Typer)                │
+│                    └─────┬─────┘                                │
+│                          │                                       │
+│          ┌───────────────┼───────────────┐                      │
+│          ▼               ▼               ▼                      │
+│   ┌─────────────┐ ┌─────────────┐ ┌─────────────┐              │
+│   │   Docker    │ │  AGENTS.    │ │  Datasette  │              │
+│   │   SDK       │ │  lock       │ │  (logging)  │              │
+│   │  (Python)   │ │  (Python)   │ │  (Python)   │              │
+│   └──────┬──────┘ └─────────────┘ └─────────────┘              │
+│          │                                                       │
+│          ▼                                                       │
+│   ┌─────────────────────────────────────────────┐               │
+│   │           Docker Hub: vibepod/*             │               │
+│   │                                             │               │
+│   │  vibepod/claude    vibepod/gemini          │               │
+│   │  vibepod/opencode  vibepod/devstral        │               │
+│   │  vibepod/auggie    vibepod/datasette       │               │
+│   └─────────────────────────────────────────────┘               │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Repository Structure
+
+### VibePod Organization
+
+| Repository | Purpose |
+|------------|---------|
+| `VibePod/vibepod` | Main CLI tool (this spec) |
+| `VibePod/docs` | Documentation site (vibepod.dev) |
+| `VibePod/skills` | Official skills collection |
+
+### Container Repositories
+
+| Repository | Docker Image |
+|------------|--------------|
+| `nezhar/claude-container` | `vibepod/claude` |
+| `nezhar/gemini-container` | `vibepod/gemini` |
+| `nezhar/opencode-container` | `vibepod/opencode` |
+| `nezhar/devstral-container` | `vibepod/devstral` |
+| `nezhar/auggie-container` | `vibepod/auggie` |
+
+### External Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `luml-ai/AGENTS.lock` | Skills & config sync |
+
+---
+
+## Supported Agents
+
+| Agent | Provider | Image | Config Dir |
+|-------|----------|-------|------------|
+| claude | Anthropic | `vibepod/claude` | `~/.config/vibepod/agents/claude` |
+| gemini | Google | `vibepod/gemini` | `~/.config/vibepod/agents/gemini` |
+| opencode | OpenAI | `vibepod/opencode` | `~/.config/vibepod/agents/opencode` |
+| devstral | Mistral | `vibepod/devstral` | `~/.config/vibepod/agents/devstral` |
+| auggie | Augment | `vibepod/auggie` | `~/.config/vibepod/agents/auggie` |
+
+---
+
+## Installation Methods
+
+### Primary: pipx
+
+```bash
+pipx install vibepod
+```
+
+### Secondary: pip
+
+```bash
+pip install vibepod
+```
+
+### Tertiary: Binary (via PyInstaller)
+
+```bash
+# macOS/Linux
+curl -fsSL https://vibepod.dev/install.sh | bash
+
+# Windows
+irm https://vibepod.dev/install.ps1 | iex
+```
+
+### Development
+
+```bash
+git clone https://github.com/VibePod/vibepod
+cd vibepod
+pip install -e ".[dev]"
+```
+
+---
+
+## Links
+
+| Resource | URL |
+|----------|-----|
+| Website | https://vibepod.dev |
+| GitHub | https://github.com/VibePod/vibepod |
+| Docker Hub | https://hub.docker.com/u/vibepod |
+| PyPI | https://pypi.org/project/vibepod |
+| AGENTS.lock | https://github.com/luml-ai/AGENTS.lock |