Skip to content

Commit 5f6bb1f

Browse files
shuvebclaude
shuveb
and
claude
committed
Add ralph subcommand for auto-invoking coding agents
Implements the `mfbt ralph` command that orchestrates coding agents to implement pending features. Includes CLI + interactive TUI mode, agent subprocess management with stream-json parsing, retry logic, log capture, and progress tracking via the mfbt API. Also adds --append-system-prompt internally to guide agent behavior (no plan mode, follow mfbt MCP workflow), disables response caching for ralph to avoid stale progress data, and includes PyPI packaging setup. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent a7b8be5 commit 5f6bb1f

34 files changed

+6408
-13
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,3 +40,36 @@ jobs:
4040
--cov-report=term-missing
4141
--cov-fail-under=75
4242
-q
43+
44+
installation-test:
45+
runs-on: ubuntu-latest
46+
needs: quality
47+
strategy:
48+
matrix:
49+
python-version: ["3.10", "3.11", "3.12"]
50+
steps:
51+
- uses: actions/checkout@v4
52+
53+
- uses: actions/setup-python@v5
54+
with:
55+
python-version: ${{ matrix.python-version }}
56+
57+
- name: Install uv
58+
run: pip install uv
59+
60+
- name: Create venv and install dev dependencies
61+
run: |
62+
uv venv
63+
uv pip install -e . -r requirements-dev.txt
64+
65+
- name: Run installation tests
66+
run: uv run pytest tests/integration/test_installation.py -v
67+
68+
- name: Upload test logs
69+
if: always()
70+
uses: actions/upload-artifact@v4
71+
with:
72+
name: installation-test-logs-py${{ matrix.python-version }}
73+
path: |
74+
tests/integration/test_installation.py
75+
retention-days: 14

‎.github/workflows/release.yml‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
name: Release to PyPI
2+
3+
on:
4+
release:
5+
types: [published]
6+
7+
permissions:
8+
contents: read
9+
10+
jobs:
11+
build:
12+
name: Build distribution packages
13+
runs-on: ubuntu-latest
14+
steps:
15+
- uses: actions/checkout@v4
16+
17+
- uses: actions/setup-python@v5
18+
with:
19+
python-version: "3.12"
20+
21+
- name: Install build tools
22+
run: pip install build
23+
24+
- name: Build sdist and wheel
25+
run: python -m build
26+
27+
- name: Verify distributions
28+
run: |
29+
pip install twine
30+
twine check dist/*
31+
32+
- uses: actions/upload-artifact@v4
33+
with:
34+
name: dist
35+
path: dist/
36+
37+
test-installation:
38+
name: Test installation from wheel
39+
needs: build
40+
runs-on: ubuntu-latest
41+
strategy:
42+
matrix:
43+
python-version: ["3.10", "3.11", "3.12"]
44+
steps:
45+
- uses: actions/download-artifact@v4
46+
with:
47+
name: dist
48+
path: dist/
49+
50+
- uses: actions/setup-python@v5
51+
with:
52+
python-version: ${{ matrix.python-version }}
53+
54+
- name: Install from wheel
55+
run: pip install dist/*.whl
56+
57+
- name: Verify entry point
58+
run: mfbt --version
59+
60+
- name: Verify help
61+
run: mfbt --help
62+
63+
- name: Verify module import
64+
run: python -c "import mfbt; print('ok')"
65+
66+
publish-testpypi:
67+
name: Publish to TestPyPI
68+
needs: [build, test-installation]
69+
runs-on: ubuntu-latest
70+
if: github.event.release.prerelease
71+
environment: testpypi
72+
permissions:
73+
id-token: write
74+
steps:
75+
- uses: actions/download-artifact@v4
76+
with:
77+
name: dist
78+
path: dist/
79+
80+
- name: Publish to TestPyPI
81+
uses: pypa/gh-action-pypi-publish@release/v1
82+
with:
83+
repository-url: https://test.pypi.org/legacy/
84+
85+
publish-pypi:
86+
name: Publish to PyPI
87+
needs: [build, test-installation]
88+
runs-on: ubuntu-latest
89+
if: "!github.event.release.prerelease"
90+
environment: pypi
91+
permissions:
92+
id-token: write
93+
steps:
94+
- uses: actions/download-artifact@v4
95+
with:
96+
name: dist
97+
path: dist/
98+
99+
- name: Publish to PyPI
100+
uses: pypa/gh-action-pypi-publish@release/v1

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,5 +21,8 @@ venv/
2121
.ruff_cache/
2222
.coverage
2323

24+
# PyPI config (tokens)
25+
.pypirc
26+
2427
# OS
2528
.DS_Store

‎.pypirc.template‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Copy this file to ~/.pypirc (or ./.pypirc) and fill in your API tokens.
2+
# NEVER commit real tokens to version control.
3+
#
4+
# Generate tokens at:
5+
# - TestPyPI: https://test.pypi.org/manage/account/token/
6+
# - PyPI: https://pypi.org/manage/account/token/
7+
8+
[distutils]
9+
index-servers =
10+
pypi
11+
testpypi
12+
13+
[pypi]
14+
username = __token__
15+
password = pypi-XXXX
16+
17+
[testpypi]
18+
repository = https://test.pypi.org/legacy/
19+
username = __token__
20+
password = pypi-XXXX

‎CLAUDE.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,3 +93,12 @@ This project uses the **mfbt MCP server**, which exposes a virtual filesystem (V
9393
- Use `grep` to search across specs and prompt plans
9494
- For team communication (posting comments), see `/for-coding-agents/mfbt-usage-guide/`
9595
- To update status: `in_progress` on features when starting, `is_complete` on implementations when done
96+
97+
## Development
98+
99+
- **Venv:** `.venv/bin/python`, `.venv/bin/pytest`
100+
- **Run tests:** `.venv/bin/pytest tests/unit/ralph/ -v`
101+
- **API response formats:** List endpoints (`/features`, `/implementations`) return **paginated** `{"items": [...], "total": N, ...}` — always extract via `body["items"]`. Some endpoints (`/brainstorming-phases`) return plain lists. See `src/mfbt/tui/data_provider.py` for the canonical parsing pattern.
102+
- **Ralph subcommand:** `src/mfbt/commands/ralph/` — orchestrator, display (console), tui_display (Textual), agent runner, progress (API), prompt builder, types
103+
- **Ralph TUI:** Standalone Textual app (`tui_app.py`), separate from main mfbt TUI. Uses `RalphTUIDisplay` adapter (same 8-method interface as `RalphDisplay`) with `call_from_thread()` to marshal UI updates from the orchestrator's worker thread.
104+
- **Display duck typing:** `RalphOrchestrator.display` is typed as `Any` — both `RalphDisplay` and `RalphTUIDisplay` are structurally compatible (same 8 methods).

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Zipstack
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 50 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,14 @@
11
# mfbt CLI
22

3-
Command-line tool for the mfbt platform. Provides both an interactive TUI mode and traditional subcommands for managing mfbt projects.
3+
Command-line tool for the [mfbt](https://mfbt.ai) platform. Provides both an interactive TUI mode and traditional subcommands for managing mfbt projects.
4+
5+
## Features
6+
7+
- **Interactive TUI** -- K9S-style keyboard-driven interface for navigating projects, phases, modules, and features
8+
- **Subcommands** -- Traditional CLI commands for scripting and automation (`auth`, `projects`, `ralph`, and more)
9+
- **OAuth 2.1 Authentication** -- Secure browser-based login with PKCE and API key support
10+
- **Real-time Updates** -- WebSocket-powered job monitoring and status tracking
11+
- **Agent Orchestration** -- Auto-invoke coding agents to implement pending features with `mfbt ralph`
412

513
## Requirements
614

@@ -12,11 +20,49 @@ Command-line tool for the mfbt platform. Provides both an interactive TUI mode a
1220
pip install mfbt-cli
1321
```
1422

23+
## Quick Start
24+
25+
```bash
26+
# Authenticate with the mfbt platform
27+
mfbt auth login
28+
29+
# List your projects
30+
mfbt projects list
31+
32+
# Launch the interactive TUI
33+
mfbt
34+
35+
# Show version
36+
mfbt --version
37+
```
38+
39+
## Usage
40+
41+
```bash
42+
# Run with verbose output
43+
mfbt -v
44+
mfbt -vv # debug
45+
mfbt -vvv # trace
46+
47+
# Authentication commands
48+
mfbt auth login
49+
mfbt auth status
50+
mfbt auth logout
51+
52+
# Project management
53+
mfbt projects list
54+
mfbt projects show
55+
mfbt projects switch
56+
57+
# Auto-invoke coding agents
58+
mfbt ralph
59+
```
60+
1561
## Development Setup
1662

1763
```bash
1864
# Clone the repository
19-
git clone <repo-url>
65+
git clone https://github.com/Zipstack/mfbt-cli.git
2066
cd mfbt-cli
2167

2268
# Create a virtual environment
@@ -37,14 +83,6 @@ ruff check src/ tests/
3783
mypy src/
3884
```
3985

40-
## Usage
41-
42-
```bash
43-
# Show version
44-
mfbt --version
86+
## License
4587

46-
# Run with verbose output
47-
mfbt -v
48-
mfbt -vv # debug
49-
mfbt -vvv # trace
50-
```
88+
MIT -- see [LICENSE](LICENSE) for details.

0 commit comments

Comments
 (0)