ralph-loop 0.1.0__tar.gz

ralph_loop-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12"]
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Type check
+        run: mypy src/
+
+      - name: Lint
+        run: ruff check src/
+
+      - name: Format check
+        run: ruff format --check src/
+
+      - name: Test
+        run: pytest --cov --cov-report=xml
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v4
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+        with:
+          file: coverage.xml

ralph_loop-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing & coverage
+.coverage
+.pytest_cache/
+htmlcov/
+
+# Type checking & linting
+.mypy_cache/
+.ruff_cache/
+
+# Ralph local state
+.ralph/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+
+# Development artifacts
+PROMPT.md
+PROMPT-*.md
+
+# AI Stuff
+CLAUDE.md
+AGENTS.md

ralph_loop-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ilja Weber <info@ilja-weber.de>
+
+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.

ralph_loop-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: ralph-loop
+Version: 0.1.0
+Summary: Autonomous development loop with context rotation
+Author-email: Ilja Weber <info@ilja-weber.de>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: pathspec>=0.12.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.2; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Ralph
+
+Stop cleaning up after your AI coding agent.
+
+Ralph supervises Claude Code (and other agents soon) to actually finish what they start.
+When Claude loses track, declares "done" prematurely, or forgets earlier decisions -- Ralph catches it.
+
+## Who This Is For
+
+- You use Claude Code or similar AI coding tools
+- You're building real projects, not just experimenting
+- You've been frustrated by half-finished AI output
+- You want better results, even if it costs more tokens
+
+## Quick Start
+
+1. **Install and initialize**
+   ```bash
+   pip install ralph-loop
+   ralph init
+   ```
+
+2. **Describe what you want built** (in PROMPT.md)
+   ```markdown
+   # Goal
+   Add a contact form that emails submissions to me.
+
+   # Success Criteria
+   - [ ] Form has name, email, message fields
+   - [ ] Validates email format before sending
+   - [ ] Shows success message after submission
+   - [ ] Emails go to contact@mysite.com
+   ```
+
+3. **Let Ralph supervise the build**
+   ```bash
+   ralph run
+   ```
+   Ralph keeps Claude working until all criteria are actually met. Verified 3 times to make sure nothing was missed.
+
+## How It Works
+
+Claude Code is powerful, but on bigger tasks it can:
+- **Lose context** as the conversation grows
+- **Forget decisions** made earlier in the session
+- **Declare "done"** when things clearly aren't
+
+Ralph solves this by **breaking big tasks into fresh-context chunks**.
+
+After each chunk, Ralph:
+1. Saves what Claude learned and accomplished (so nothing is lost)
+2. Starts a fresh session (so context stays clean)
+3. Hands off the state (so Claude picks up where it left off)
+
+When Claude says "done", Ralph doesn't just trust it—it verifies 3 times with fresh eyes. If anything was missed, work continues.
+
+**Result:** Tasks that used to fail halfway through now complete reliably.
+
+## The Tradeoff
+
+Ralph uses more tokens than running Claude directly. Each rotation is a fresh API call, and verification adds more.
+
+**But:** You'll spend less time debugging, less time re-prompting, and less time cleaning up half-finished work. For many tasks, the extra tokens are worth it.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `ralph init` | Initialize Ralph in the current directory |
+| `ralph run` | Supervise Claude until the goal is complete |
+| `ralph status` | Show current progress |
+| `ralph reset` | Start fresh |
+| `ralph history` | View logs from previous sessions |
+
+## Configuration
+
+The `.ralph/` directory contains local state and should not be committed:
+
+```
+# .gitignore
+.ralph/
+```
+
+## Documentation
+
+- [Getting Started](./docs/getting-started.md) - Full setup guide
+- [Writing Effective Prompts](./docs/writing-prompts.md) - Get better results
+- [Troubleshooting](./docs/troubleshooting/index.md) - When things go wrong
+- [Full Documentation](./docs/README.md) - Everything else
+
+## Built By
+
+Ralph was created by [Ilja Weber](https://linkedin.com/in/ilja-weber-bb7135b5) to solve my own frustrations with AI coding agents declaring "done" too early.
+
+Follow for updates:
+- [LinkedIn](https://www.linkedin.com/in/ilja-weber-bb7135b5)
+- [Twitter/X](https://x.com/iwebercodes)
+
+## License
+
+MIT

ralph_loop-0.1.0/README.md

@@ -0,0 +1,101 @@
+# Ralph
+
+Stop cleaning up after your AI coding agent.
+
+Ralph supervises Claude Code (and other agents soon) to actually finish what they start.
+When Claude loses track, declares "done" prematurely, or forgets earlier decisions -- Ralph catches it.
+
+## Who This Is For
+
+- You use Claude Code or similar AI coding tools
+- You're building real projects, not just experimenting
+- You've been frustrated by half-finished AI output
+- You want better results, even if it costs more tokens
+
+## Quick Start
+
+1. **Install and initialize**
+   ```bash
+   pip install ralph-loop
+   ralph init
+   ```
+
+2. **Describe what you want built** (in PROMPT.md)
+   ```markdown
+   # Goal
+   Add a contact form that emails submissions to me.
+
+   # Success Criteria
+   - [ ] Form has name, email, message fields
+   - [ ] Validates email format before sending
+   - [ ] Shows success message after submission
+   - [ ] Emails go to contact@mysite.com
+   ```
+
+3. **Let Ralph supervise the build**
+   ```bash
+   ralph run
+   ```
+   Ralph keeps Claude working until all criteria are actually met. Verified 3 times to make sure nothing was missed.
+
+## How It Works
+
+Claude Code is powerful, but on bigger tasks it can:
+- **Lose context** as the conversation grows
+- **Forget decisions** made earlier in the session
+- **Declare "done"** when things clearly aren't
+
+Ralph solves this by **breaking big tasks into fresh-context chunks**.
+
+After each chunk, Ralph:
+1. Saves what Claude learned and accomplished (so nothing is lost)
+2. Starts a fresh session (so context stays clean)
+3. Hands off the state (so Claude picks up where it left off)
+
+When Claude says "done", Ralph doesn't just trust it—it verifies 3 times with fresh eyes. If anything was missed, work continues.
+
+**Result:** Tasks that used to fail halfway through now complete reliably.
+
+## The Tradeoff
+
+Ralph uses more tokens than running Claude directly. Each rotation is a fresh API call, and verification adds more.
+
+**But:** You'll spend less time debugging, less time re-prompting, and less time cleaning up half-finished work. For many tasks, the extra tokens are worth it.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `ralph init` | Initialize Ralph in the current directory |
+| `ralph run` | Supervise Claude until the goal is complete |
+| `ralph status` | Show current progress |
+| `ralph reset` | Start fresh |
+| `ralph history` | View logs from previous sessions |
+
+## Configuration
+
+The `.ralph/` directory contains local state and should not be committed:
+
+```
+# .gitignore
+.ralph/
+```
+
+## Documentation
+
+- [Getting Started](./docs/getting-started.md) - Full setup guide
+- [Writing Effective Prompts](./docs/writing-prompts.md) - Get better results
+- [Troubleshooting](./docs/troubleshooting/index.md) - When things go wrong
+- [Full Documentation](./docs/README.md) - Everything else
+
+## Built By
+
+Ralph was created by [Ilja Weber](https://linkedin.com/in/ilja-weber-bb7135b5) to solve my own frustrations with AI coding agents declaring "done" too early.
+
+Follow for updates:
+- [LinkedIn](https://www.linkedin.com/in/ilja-weber-bb7135b5)
+- [Twitter/X](https://x.com/iwebercodes)
+
+## License
+
+MIT

ralph_loop-0.1.0/docs/README.md

@@ -0,0 +1,42 @@
+# Ralph Documentation
+
+Ralph supervises your AI coding agent to actually finish what it starts.
+
+## Quick Navigation
+
+**Just getting started?**
+[Get up and running in 5 minutes](./getting-started.md)
+
+**Something went wrong?**
+[Troubleshooting guide](./troubleshooting/index.md)
+
+**Need examples?**
+[See real PROMPT.md examples](./examples/index.md)
+
+**Looking up a command?**
+[Command reference](./commands/index.md)
+
+**Want to understand how it works?**
+[How Ralph works](./how-it-works.md)
+
+## In a Hurry?
+
+```bash
+pip install ralph-loop
+ralph init
+# Edit PROMPT.md with your goal
+ralph run
+```
+
+That's it. Ralph will keep Claude working until your goal is complete, verified 3 times.
+
+## What is Ralph?
+
+When you give Claude Code a complex task, it can lose context, forget decisions, or declare "done" too early. Ralph fixes this by breaking work into fresh-context chunks and maintaining state between them.
+
+Ralph is for anyone who:
+- Uses AI coding agents to build projects
+- Gets frustrated when agents lose track of what they're doing
+- Wants reliable completion without constant supervision
+
+[Learn more about how Ralph works](./how-it-works.md)