clawforge-cli 1.2.0__py3-none-any.whl

clawforge/cli.py

@@ -0,0 +1,24 @@
+"""ClawForge CLI entry point for pip/uv installation."""
+import os
+import sys
+import subprocess
+
+def main():
+    """Delegate to the real shell-based clawforge CLI."""
+    clawforge_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    clawforge_bin = os.path.join(clawforge_dir, "bin", "clawforge")
+
+    if not os.path.exists(clawforge_bin):
+        # Fallback: try PATH
+        clawforge_bin = "clawforge"
+
+    try:
+        result = subprocess.run([clawforge_bin] + sys.argv[1:])
+        sys.exit(result.returncode)
+    except FileNotFoundError:
+        print("Error: clawforge binary not found. Install from source:")
+        print("  git clone https://github.com/cyperx84/clawforge.git && cd clawforge && ./install.sh")
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

clawforge_cli-1.2.0.dist-info/METADATA

@@ -0,0 +1,325 @@
+Metadata-Version: 2.4
+Name: clawforge-cli
+Version: 1.2.0
+Summary: Multi-mode coding workflow CLI for orchestrating AI coding agents
+Project-URL: Homepage, https://github.com/cyperx84/clawforge
+Project-URL: Repository, https://github.com/cyperx84/clawforge
+Author: cyperx84
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,cli,coding,orchestration
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# ClawForge
+
+```text
+   ________                ______
+  / ____/ /___ __      __ / ____/___  _________ ____
+ / /   / / __ `/ | /| / // /_  / __ \/ ___/ __ `/ _ \
+/ /___/ / /_/ /| |/ |/ // __/ / /_/ / /  / /_/ /  __/
+\____/_/\__,_/ |__/|__//_/    \____/_/   \__, /\___/
+                                         /____/
+```
+
+**Multi-mode coding workflow CLI** — from quick patches to parallel agent orchestration with Claude Code and Codex.
+
+## Inspired By
+
+This project was inspired by [Elvis's "OpenClaw + Codex/Claude Code Agent Swarm" workflow](https://x.com/elvissun/article/2025920521871716562) — a battle-tested system for managing a fleet of AI coding agents.
+
+## What It Does
+
+ClawForge manages coding agents running in tmux sessions on isolated git worktrees. Three workflow modes match task complexity:
+
+| Mode | Use Case | Agents |
+|------|----------|--------|
+| **Sprint** | Single task, full dev cycle | 1 |
+| **Review** | Quality gate on existing PR | 0 (analysis only) |
+| **Swarm** | Parallel orchestration | N (decomposed) |
+
+Plus management commands: `steer`, `attach`, `stop`, `watch --daemon`, `status`, `dashboard`.
+
+## Architecture
+
+```
+                        clawforge CLI
+                            │
+            ┌───────────────┼───────────────┐
+            │               │               │
+       Workflow Modes   Management       Direct Access
+       ┌───────────┐   ┌──────────┐    ┌──────────────┐
+       │ sprint    │   │ status   │    │ scope  spawn │
+       │ review    │   │ attach   │    │ notify merge │
+       │ swarm     │   │ steer    │    │ clean  learn │
+       └─────┬─────┘   │ stop    │    └──────────────┘
+             │         │ watch    │
+             │         │ dashboard│
+             │         └────┬─────┘
+             │              │
+             └──────┬───────┘
+                    │
+          ┌─────────┼─────────┐
+          │         │         │
+        tmux    git worktree  gh CLI
+        sessions  (isolated)  (PRs/CI)
+          │
+        coding agents
+        (claude / codex)
+```
+
+## Installation
+
+| Method | Command | Best For |
+|--------|---------|----------|
+| Homebrew | `brew install cyperx84/tap/clawforge` | macOS users (recommended) |
+| npm | `npm install -g @cyperx84/clawforge` | Node.js users |
+| uv | `uv tool install clawforge` | Python users |
+| bun | `bun install -g @cyperx84/clawforge` | Bun users |
+| Source | See below | Development |
+
+### Homebrew (recommended for macOS)
+
+```bash
+brew tap cyperx84/tap
+brew install cyperx84/tap/clawforge
+```
+
+Upgrade later:
+
+```bash
+brew update
+brew upgrade clawforge
+```
+
+### npm / bun
+
+```bash
+# npm
+npm install -g @cyperx84/clawforge
+
+# bun
+bun install -g @cyperx84/clawforge
+```
+
+Upgrade later:
+
+```bash
+npm update -g @cyperx84/clawforge
+# or
+bun update -g @cyperx84/clawforge
+```
+
+### uv (Python)
+
+```bash
+uv tool install clawforge
+```
+
+Upgrade later:
+
+```bash
+uv tool upgrade clawforge
+```
+
+### Source install
+
+```bash
+git clone https://github.com/cyperx84/clawforge.git
+cd clawforge
+./install.sh --openclaw
+```
+
+That command will:
+- symlink `clawforge` into `~/.local/bin`
+- wire up `SKILL.md` for OpenClaw
+- create missing directories if needed
+
+### Install modes
+
+#### 1) OpenClaw skill mode
+
+```bash
+./install.sh --openclaw
+```
+
+#### 2) Standalone CLI mode
+
+```bash
+./install.sh --standalone
+```
+
+#### 3) Custom bin path
+
+```bash
+./install.sh --openclaw --bin-dir ~/.bin
+```
+
+### Manual install (if you prefer explicit symlinks)
+
+```bash
+mkdir -p ~/.local/bin
+ln -sf "$(pwd)/bin/clawforge" ~/.local/bin/clawforge
+
+# Optional OpenClaw skill wiring
+mkdir -p ~/.openclaw/skills/clawforge/scripts
+ln -sf "$(pwd)/SKILL.md" ~/.openclaw/skills/clawforge/SKILL.md
+ln -sf "$(pwd)/bin/clawforge" ~/.openclaw/skills/clawforge/scripts/clawforge
+```
+
+### Verify install
+
+```bash
+clawforge version
+clawforge help
+```
+
+### Prerequisites
+
+- `bash` (4+), `jq`, `git`, `tmux`
+- `gh` (GitHub CLI, authenticated)
+- `claude` and/or `codex` CLI
+
+
+## Documentation
+
+Full docs live in [`docs/`](./docs/README.md):
+
+- [Getting Started](./docs/getting-started.md)
+- [Workflow Modes](./docs/workflow-modes.md)
+- [Command Reference](./docs/command-reference.md)
+- [Scenario Playbooks](./docs/scenarios.md)
+- [Dashboard (Go TUI)](./docs/dashboard.md)
+- [Architecture](./docs/architecture.md)
+- [Fleet Ops](./docs/fleet-ops.md)
+- [Evaluation Loop](./docs/evaluation.md)
+- [Configuration](./docs/configuration.md)
+- [Troubleshooting](./docs/troubleshooting.md)
+- [FAQ](./docs/faq.md)
+- [Changelog](./CHANGELOG.md)
+
+## Quick Start
+
+### Sprint — the workhorse
+
+```bash
+# Single agent, full dev cycle (auto-detects repo from cwd)
+clawforge sprint "Add JWT authentication middleware"
+
+# Quick patch mode — auto-merge, skip review
+clawforge sprint "Fix typo in readme" --quick
+
+# With explicit options
+clawforge sprint ~/github/api "Fix null pointer" --branch fix/null-ptr --agent codex
+```
+
+### Review — quality gate
+
+```bash
+clawforge review --pr 42
+clawforge review --pr 42 --fix               # Spawn agent to fix issues
+clawforge review --pr 42 --reviewers claude,gemini,codex
+```
+
+### Swarm — parallel agents
+
+```bash
+clawforge swarm "Migrate all tests from jest to vitest"
+clawforge swarm "Add i18n to all strings" --max-agents 4
+```
+
+### Monitor & Manage
+
+```bash
+clawforge status                   # Short IDs: #1, #2, #3
+clawforge attach 1                 # Attach to agent tmux session
+clawforge steer 1 "Use bcrypt"    # Course-correct running agent
+clawforge steer 3.2 "Skip legacy" # Steer sub-agent 2 of swarm task 3
+clawforge stop 1 --yes            # Stop agent
+clawforge watch --daemon           # Background monitoring + CI feedback
+clawforge dashboard                # Full overview + system health
+```
+
+## Commands
+
+### Workflow Modes
+
+| Command | Description | Key Flags |
+|---------|-------------|-----------|
+| `sprint` | Single agent, full dev cycle | `--quick`, `--branch`, `--agent`, `--auto-merge`, `--dry-run` |
+| `review` | Quality gate on existing PR | `--pr`, `--fix`, `--reviewers`, `--dry-run` |
+| `swarm` | Parallel multi-agent orchestration | `--max-agents`, `--agent`, `--auto-merge`, `--dry-run` |
+
+### Management
+
+| Command | Description | Key Flags |
+|---------|-------------|-----------|
+| `status` | Show tracked tasks with short IDs | `--status` |
+| `attach` | Attach to agent tmux session | (task ID) |
+| `steer` | Course-correct running agent | (task ID, message) |
+| `stop` | Stop a running agent | `--yes`, `--clean` |
+| `watch` | Monitor agent health | `--daemon`, `--stop`, `--json`, `--interval` |
+| `dashboard` | Overview + system health | (none) |
+| `clean` | Clean up completed tasks | `--all-done`, `--stale-days`, `--dry-run` |
+| `learn` | Record learnings | `--auto`, `--notes`, `--memory` |
+
+### Fleet Ops (v0.6)
+
+| Command | Description | Key Flags |
+|---------|-------------|-----------|
+| `memory` | Per-repo agent memory | `show`, `add`, `search`, `forget`, `clear` |
+| `init` | Scan project, generate initial memories | `--claude-md` |
+| `history` | Show completed task history | `--repo`, `--mode`, `--limit`, `--all` |
+
+### Direct Module Access (via `clawforge help --all`)
+
+| Command | Description |
+|---------|-------------|
+| `scope` | Assemble prompt with context |
+| `spawn` | Create worktree + launch agent |
+| `notify` | Send Discord notification |
+| `merge` | Merge PR with safety checks |
+| `run` | Scope + spawn in one step (legacy) |
+
+**Global flag:** `--verbose` enables debug logging for any command.
+
+## Smart Behaviors
+
+- **Auto-repo detection** — No `--repo` needed if you're in a git repo
+- **Auto-branch naming** — `sprint/<slug>`, `quick/<slug>`, `swarm/<slug>` with collision detection
+- **Short task IDs** — `#1`, `3.2` instead of full slugs
+- **CI feedback loop** — Watch detects CI failure, auto-steers agent with error context (up to 2 retries)
+- **Escalation suggestions** — Quick mode detects complex tasks, suggests full sprint
+- **Conflict detection** — Dashboard warns when swarm agents touch overlapping files
+- **RAM warnings** — Prompts when spawning >3 agents
+- **Agent memory** — Per-repo knowledge base injected into agent prompts (max 20 entries)
+- **Project init** — Auto-detect language, framework, test runner and seed memories
+
+## Configuration
+
+Edit `config/defaults.json`:
+
+```json
+{
+  "default_agent": "claude",
+  "default_model_claude": "claude-sonnet-4-5",
+  "default_model_codex": "gpt-5.3-codex",
+  "ci_retry_limit": 2,
+  "ram_warn_threshold": 3,
+  "reviewers": ["claude", "gemini"],
+  "auto_simplify": true,
+  "notify": {
+    "defaultChannel": "channel:..."
+  }
+}
+```
+
+## Testing
+
+```bash
+./tests/run-all-tests.sh
+```
+
+## License
+
+MIT

clawforge_cli-1.2.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+clawforge/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+clawforge/cli.py,sha256=5wTAE8vwjVWtgzg11-z_XqV3E6okhugF7Mf_N4NJAjw,798
+clawforge_cli-1.2.0.dist-info/METADATA,sha256=vo-R1pNrF2q-P6QRQM0eo2PLpR7hDUY51uWYS8LlSiI,9475
+clawforge_cli-1.2.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+clawforge_cli-1.2.0.dist-info/entry_points.txt,sha256=HraAmZm_4MWBtRZVvAyqaFCc0E4mA2rsGLD-Yrv8Wls,49
+clawforge_cli-1.2.0.dist-info/licenses/LICENSE,sha256=duXwqXoMKU9SqNuI8PAJHbK_smLx__Fnn2hLNsZeGhA,1065
+clawforge_cli-1.2.0.dist-info/RECORD,,

clawforge_cli-1.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

clawforge_cli-1.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+clawforge = clawforge.cli:main

clawforge_cli-1.2.0.dist-info/licenses/LICENSE

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