pip-boy 0.1.0__tar.gz

pip_boy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pip-Boy 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.

pip_boy-0.1.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: pip-boy
+Version: 0.1.0
+Summary: Personal assistant agent with persistent memory and configurable persona
+License-Expression: MIT
+Project-URL: Repository, https://github.com/ByeDream/Pip-Boy
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anthropic<1,>=0.49
+Requires-Dist: pydantic-settings<3,>=2.8
+Requires-Dist: pyreadline3<4,>=3.5; sys_platform == "win32"
+Requires-Dist: tavily-python>=0.5
+Requires-Dist: ddgs>=7
+Requires-Dist: pyyaml<7,>=6
+Requires-Dist: httpx>=0.27
+Requires-Dist: wecom-aibot-python-sdk>=1.0
+Requires-Dist: qrcode>=7
+Dynamic: license-file
+
+# Pip-Boy
+
+<p align="center">
+  <img src="docs/Imgs/Pip-BoyAdArtPrint.jpg" width="480" alt="Pip-Boy 3000 Mark IV" />
+</p>
+
+A personal assistant agent with persistent memory and a configurable persona, providing a chat-based interface for workstation interaction. Built on Anthropic's Claude API, it supports multi-agent teamwork, task planning, git worktree isolation, and extensible skills.
+
+## Features
+
+### Core
+
+- **Conversational REPL** — Interactive chat loop with readline history and UTF-8 support
+- **Persona System** — Fixed lead persona ("Pip-Boy") with customizable teammate personas via Markdown files
+- **Web Search** — Tavily integration with automatic DuckDuckGo fallback
+
+### Tools
+
+- **Filesystem** — `read`, `write`, `edit`, `glob` (sandboxed to working directory)
+- **Shell** — `bash` execution with optional **background mode** for long-running commands
+- **Web** — `web_search` and `web_fetch` for real-time information retrieval
+- **Skills** — `load_skill` dynamically loads built-in and user-defined skill guides (Markdown with YAML frontmatter)
+
+### Task Planning
+
+- **Story / Task DAG** — Two-level planning: stories (epics) contain tasks with dependency tracking
+- **Kanban Board** — `task_board_overview`, `task_board_detail` for status visualization
+- **State Machine** — Tasks flow through `pending` → `in_progress` → `in_review` → `completed` / `failed`
+- **Persistent Storage** — JSON files under `.pip/tasks/` survive across sessions
+
+### Multi-Agent Team
+
+- **Teammate Spawning** — `team_spawn` creates daemon threads with per-session model and turn limits
+- **Inbox Messaging** — JSONL-based message bus (`send`, `read_inbox`) between lead and teammates
+- **Model Selection** — Per-project `.pip/models.json` defines available models for teammate assignment
+- **Protocol Tracking** — Structured shutdown and plan approval flows
+- **CLI Commands** — `/team` for roster status, `/inbox` to peek the lead inbox
+
+### Git Worktree Isolation
+
+- **Isolated Branches** — Each subagent works in its own git worktree (`.pip/.worktrees/{name}/`, branch `wt/{name}`)
+- **Sync / Integrate / Cleanup** — Worktree lifecycle management with merge conflict detection
+- **Task Submission** — `task_submit` syncs work and transitions task status automatically
+
+### Context Management
+
+- **Micro-Compaction** — Old tool results replaced with placeholders, keeping the last N rounds intact
+- **Auto-Compaction** — When token count exceeds threshold, full transcript is saved and replaced with an LLM-generated summary
+- **Transcript Persistence** — Timestamped JSON transcripts stored under `.pip/transcripts/`
+
+### Skills (Built-in)
+
+| Skill | Purpose |
+|-------|---------|
+| `task-planning` | Structured planning with story/task breakdown |
+| `agent-team` | Multi-agent coordination and delegation |
+| `git` | Git operations and workflow guidance |
+| `code-review` | Code review methodology |
+| `create-skill` | Authoring new custom skills |
+
+### Workspace Scaffold
+
+On first run in a new project, the agent automatically creates:
+- `.pip/` directory structure (tasks, transcripts, team, skills)
+- `.pip/models.json` with default model catalog
+- `.pip/agents/pip-boy.md` default agent persona
+- `.env` from template (if missing)
+- `.gitignore` entries for `.pip/` and related paths
+- `.pip/.scaffold_manifest.json` for tracking scaffold file versions
+
+Scaffold files are version-tracked: unmodified files are auto-updated when a new version ships changes; locally modified files are left untouched with a warning.
+
+## Installation
+
+**Prerequisites:** Python >= 3.11
+
+```bash
+pip install pip-boy
+```
+
+### Development (from source)
+
+```bash
+git clone https://github.com/ByeDream/Pip-Boy.git
+cd Pip-Boy
+pip install -e .
+```
+
+## Usage
+
+```bash
+# Navigate to your target project and run
+cd /path/to/your/project
+pip-boy
+
+# Or use python -m
+python -m pip_agent
+
+# CLI-only mode (no WeChat/WeCom channels)
+pip-boy --cli
+
+# Force WeChat QR login
+pip-boy --scan
+
+# Show version
+pip-boy --version
+```
+
+On first launch, the scaffold automatically creates `.pip/` directory structure, `.env` (from template), and `.gitignore` entries in the target project. Edit the generated `.env` to fill in your `ANTHROPIC_API_KEY`, then run again.
+
+The agent uses `Path.cwd()` as its working directory — always run it from the project you want to interact with.
+
+### Updating
+
+From within a running session:
+
+```
+/update
+```
+
+Or manually:
+
+```bash
+pip install --upgrade pip-boy
+```
+
+## Configuration
+
+All configuration is done via environment variables or `.env` file.
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `ANTHROPIC_API_KEY` | **Yes** | — | Anthropic API key |
+| `ANTHROPIC_BASE_URL` | No | *(api.anthropic.com)* | Custom API endpoint (proxy support) |
+| `MODEL` | No | `claude-sonnet-4-6` | Default model for the lead agent |
+| `MAX_TOKENS` | No | `8096` | Max response tokens |
+| `SEARCH_API_KEY` | No | — | Tavily API key; falls back to DuckDuckGo |
+| `COMPACT_THRESHOLD` | No | `50000` | Token estimate to trigger auto-compaction |
+| `COMPACT_MICRO_AGE` | No | `3` | Micro-compaction: rounds of tool results to preserve |
+| `VERBOSE` | No | `true` | Verbose output |
+| `PROFILER_ENABLED` | No | `false` | Enable performance profiling |
+
+### Project-Level Files
+
+| File | Location | Purpose |
+|---|---|---|
+| `models.json` | `.pip/` | Model catalog for teammate spawning |
+| `*.md` | `.pip/team/` | Teammate persona definitions (YAML frontmatter + body) |
+| `_meta.json` + `*.json` | `.pip/tasks/{story}/` | Task board state |
+| `*.md` | `.pip/skills/` | User-defined skills |
+
+## Dependencies
+
+- [`anthropic`](https://github.com/anthropics/anthropic-sdk-python) — Claude API client
+- [`pydantic-settings`](https://github.com/pydantic/pydantic-settings) — Configuration management
+- [`tavily-python`](https://github.com/tavily-ai/tavily-python) — Web search API
+- [`ddgs`](https://github.com/deedy5/duckduckgo_search) — DuckDuckGo fallback search
+- [`pyyaml`](https://github.com/yaml/pyyaml) — YAML parsing for skills and team files
+- [`httpx`](https://github.com/encode/httpx) — HTTP client for channel communication
+- [`qrcode`](https://github.com/lincolnloop/python-qrcode) — Terminal QR code rendering for WeChat login
+- [`pyreadline3`](https://github.com/pyreadline3/pyreadline3) — Readline for Windows
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.

pip_boy-0.1.0/README.md

@@ -0,0 +1,165 @@
+# Pip-Boy
+
+<p align="center">
+  <img src="docs/Imgs/Pip-BoyAdArtPrint.jpg" width="480" alt="Pip-Boy 3000 Mark IV" />
+</p>
+
+A personal assistant agent with persistent memory and a configurable persona, providing a chat-based interface for workstation interaction. Built on Anthropic's Claude API, it supports multi-agent teamwork, task planning, git worktree isolation, and extensible skills.
+
+## Features
+
+### Core
+
+- **Conversational REPL** — Interactive chat loop with readline history and UTF-8 support
+- **Persona System** — Fixed lead persona ("Pip-Boy") with customizable teammate personas via Markdown files
+- **Web Search** — Tavily integration with automatic DuckDuckGo fallback
+
+### Tools
+
+- **Filesystem** — `read`, `write`, `edit`, `glob` (sandboxed to working directory)
+- **Shell** — `bash` execution with optional **background mode** for long-running commands
+- **Web** — `web_search` and `web_fetch` for real-time information retrieval
+- **Skills** — `load_skill` dynamically loads built-in and user-defined skill guides (Markdown with YAML frontmatter)
+
+### Task Planning
+
+- **Story / Task DAG** — Two-level planning: stories (epics) contain tasks with dependency tracking
+- **Kanban Board** — `task_board_overview`, `task_board_detail` for status visualization
+- **State Machine** — Tasks flow through `pending` → `in_progress` → `in_review` → `completed` / `failed`
+- **Persistent Storage** — JSON files under `.pip/tasks/` survive across sessions
+
+### Multi-Agent Team
+
+- **Teammate Spawning** — `team_spawn` creates daemon threads with per-session model and turn limits
+- **Inbox Messaging** — JSONL-based message bus (`send`, `read_inbox`) between lead and teammates
+- **Model Selection** — Per-project `.pip/models.json` defines available models for teammate assignment
+- **Protocol Tracking** — Structured shutdown and plan approval flows
+- **CLI Commands** — `/team` for roster status, `/inbox` to peek the lead inbox
+
+### Git Worktree Isolation
+
+- **Isolated Branches** — Each subagent works in its own git worktree (`.pip/.worktrees/{name}/`, branch `wt/{name}`)
+- **Sync / Integrate / Cleanup** — Worktree lifecycle management with merge conflict detection
+- **Task Submission** — `task_submit` syncs work and transitions task status automatically
+
+### Context Management
+
+- **Micro-Compaction** — Old tool results replaced with placeholders, keeping the last N rounds intact
+- **Auto-Compaction** — When token count exceeds threshold, full transcript is saved and replaced with an LLM-generated summary
+- **Transcript Persistence** — Timestamped JSON transcripts stored under `.pip/transcripts/`
+
+### Skills (Built-in)
+
+| Skill | Purpose |
+|-------|---------|
+| `task-planning` | Structured planning with story/task breakdown |
+| `agent-team` | Multi-agent coordination and delegation |
+| `git` | Git operations and workflow guidance |
+| `code-review` | Code review methodology |
+| `create-skill` | Authoring new custom skills |
+
+### Workspace Scaffold
+
+On first run in a new project, the agent automatically creates:
+- `.pip/` directory structure (tasks, transcripts, team, skills)
+- `.pip/models.json` with default model catalog
+- `.pip/agents/pip-boy.md` default agent persona
+- `.env` from template (if missing)
+- `.gitignore` entries for `.pip/` and related paths
+- `.pip/.scaffold_manifest.json` for tracking scaffold file versions
+
+Scaffold files are version-tracked: unmodified files are auto-updated when a new version ships changes; locally modified files are left untouched with a warning.
+
+## Installation
+
+**Prerequisites:** Python >= 3.11
+
+```bash
+pip install pip-boy
+```
+
+### Development (from source)
+
+```bash
+git clone https://github.com/ByeDream/Pip-Boy.git
+cd Pip-Boy
+pip install -e .
+```
+
+## Usage
+
+```bash
+# Navigate to your target project and run
+cd /path/to/your/project
+pip-boy
+
+# Or use python -m
+python -m pip_agent
+
+# CLI-only mode (no WeChat/WeCom channels)
+pip-boy --cli
+
+# Force WeChat QR login
+pip-boy --scan
+
+# Show version
+pip-boy --version
+```
+
+On first launch, the scaffold automatically creates `.pip/` directory structure, `.env` (from template), and `.gitignore` entries in the target project. Edit the generated `.env` to fill in your `ANTHROPIC_API_KEY`, then run again.
+
+The agent uses `Path.cwd()` as its working directory — always run it from the project you want to interact with.
+
+### Updating
+
+From within a running session:
+
+```
+/update
+```
+
+Or manually:
+
+```bash
+pip install --upgrade pip-boy
+```
+
+## Configuration
+
+All configuration is done via environment variables or `.env` file.
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `ANTHROPIC_API_KEY` | **Yes** | — | Anthropic API key |
+| `ANTHROPIC_BASE_URL` | No | *(api.anthropic.com)* | Custom API endpoint (proxy support) |
+| `MODEL` | No | `claude-sonnet-4-6` | Default model for the lead agent |
+| `MAX_TOKENS` | No | `8096` | Max response tokens |
+| `SEARCH_API_KEY` | No | — | Tavily API key; falls back to DuckDuckGo |
+| `COMPACT_THRESHOLD` | No | `50000` | Token estimate to trigger auto-compaction |
+| `COMPACT_MICRO_AGE` | No | `3` | Micro-compaction: rounds of tool results to preserve |
+| `VERBOSE` | No | `true` | Verbose output |
+| `PROFILER_ENABLED` | No | `false` | Enable performance profiling |
+
+### Project-Level Files
+
+| File | Location | Purpose |
+|---|---|---|
+| `models.json` | `.pip/` | Model catalog for teammate spawning |
+| `*.md` | `.pip/team/` | Teammate persona definitions (YAML frontmatter + body) |
+| `_meta.json` + `*.json` | `.pip/tasks/{story}/` | Task board state |
+| `*.md` | `.pip/skills/` | User-defined skills |
+
+## Dependencies
+
+- [`anthropic`](https://github.com/anthropics/anthropic-sdk-python) — Claude API client
+- [`pydantic-settings`](https://github.com/pydantic/pydantic-settings) — Configuration management
+- [`tavily-python`](https://github.com/tavily-ai/tavily-python) — Web search API
+- [`ddgs`](https://github.com/deedy5/duckduckgo_search) — DuckDuckGo fallback search
+- [`pyyaml`](https://github.com/yaml/pyyaml) — YAML parsing for skills and team files
+- [`httpx`](https://github.com/encode/httpx) — HTTP client for channel communication
+- [`qrcode`](https://github.com/lincolnloop/python-qrcode) — Terminal QR code rendering for WeChat login
+- [`pyreadline3`](https://github.com/pyreadline3/pyreadline3) — Readline for Windows
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.

pip_boy-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pip-boy"
+version = "0.1.0"
+description = "Personal assistant agent with persistent memory and configurable persona"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+dependencies = [
+    "anthropic>=0.49,<1",
+    "pydantic-settings>=2.8,<3",
+    "pyreadline3>=3.5,<4; sys_platform == 'win32'",
+    "tavily-python>=0.5",
+    "ddgs>=7",
+    "pyyaml>=6,<7",
+    "httpx>=0.27",
+    "wecom-aibot-python-sdk>=1.0",
+    "qrcode>=7",
+]
+
+[project.scripts]
+pip-boy = "pip_agent.__main__:main"
+
+[project.urls]
+Repository = "https://github.com/ByeDream/Pip-Boy"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"pip_agent.skills" = ["**/*.md"]
+"pip_agent.scaffold" = ["*.md", "*.json", "*.txt", "env.example"]

pip_boy-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pip_boy-0.1.0/src/pip_agent/__init__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("pip-boy")
+except PackageNotFoundError:
+    __version__ = "0.0.0-dev"

pip_boy-0.1.0/src/pip_agent/__main__.py

@@ -0,0 +1,29 @@
+import argparse
+import sys
+
+from pip_agent.agent import run
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(prog="pip-boy")
+    group = parser.add_mutually_exclusive_group()
+    group.add_argument("--scan", action="store_true", help="Force WeChat QR login")
+    group.add_argument("--cli", action="store_true", help="CLI-only mode")
+    group.add_argument("--version", action="store_true", help="Show version and exit")
+    args = parser.parse_args(argv)
+
+    if args.version:
+        from pip_agent import __version__
+        print(f"pip-boy {__version__}")
+        return
+
+    if args.cli:
+        run(mode="cli")
+    elif args.scan:
+        run(mode="scan")
+    else:
+        run(mode="auto")
+
+
+if __name__ == "__main__":
+    main()