kaizen-loop 0.1.0__tar.gz

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

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v8.2.0
+      - run: uvx ruff check src/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v8.2.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv venv
+      - run: uv pip install -e ".[dev]"
+      - run: uv run python -m pytest

kaizen_loop-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,32 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v8.2.0
+        with:
+          python-version: "3.12"
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

kaizen_loop-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+.venv/
+venv/
+.kaizen/

kaizen_loop-0.1.0/LICENSE

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

kaizen_loop-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: kaizen-loop
+Version: 0.1.0
+Summary: Continuous code improvement: autonomous work → review → fix → ship
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'

kaizen_loop-0.1.0/README.md

@@ -0,0 +1,184 @@
+# kaizen-loop
+
+Continuous code improvement: autonomous work → review → fix → ship.
+
+A zero-dependency Python harness that drives [opencode](https://opencode.ai) through the full cycle of writing, validating, and shipping code — fully autonomous.
+
+## Quick start
+
+```bash
+# Install
+pip install -e .
+
+# Run
+kaizen "add a --json flag to the status command"
+```
+
+That's it. kaizen creates an isolated branch, the agent does the work, the pipeline reviews it, fixes what it can, pushes to origin, and opens a PR.
+
+### Prerequisites
+
+- Python 3.10+
+- [opencode](https://opencode.ai) (`curl -fsSL https://opencode.ai/install | bash`)
+- `git`
+- `gh` CLI (for PR creation)
+
+### Options
+
+```
+kaizen "prompt" [-C /path/to/repo] [--max-iterations N] [--max-review-rounds N] [--no-worktree] [--server-url URL]
+```
+
+| Option | Meaning |
+|---|---|
+| `-C, --directory` | Path to git repo (default: current dir) |
+| `--max-iterations` | Max work iterations |
+| `--max-review-rounds` | Max review rounds |
+| `--no-worktree` | Work in current tree instead of a worktree |
+| `--opencode-bin` | Path to opencode binary |
+| `--server-url` | Reuse an existing `opencode serve` instance (e.g. `http://127.0.0.1:4096`) |
+
+## How it works
+
+```
+                    kaizen "add --json flag"
+                               │
+                   ┌───────────────────────────┐
+                   │  SETUP                     │
+                   │  fetch origin/main          │
+                   │  create branch kaizen/<slug>│
+                   │  create isolated worktree   │
+                   └────────────┬──────────────┘
+                                │
+                ┌───────────────────────────────┐
+                │  WORK                         │
+                │  agent reads prompt + notes    │
+                │  makes changes, commits        │
+                │  repeats until done or limit   │
+                └───────────────┬───────────────┘
+                                │
+                   ┌────────────────────────────┐
+                    │  REVIEW                     │
+                    │  agent reviews diff          │
+                    │  returns structured findings │
+                    │  ┌────────────────────────┐ │
+                    │  │  auto-fix findings?     │ │
+                    │  │  → agent fixes, re-review│ │
+                    │  └────────────────────────┘ │
+                    └────────────┬───────────────┘
+                                │
+                      ┌──────────────────┐
+                      │  SHIP            │
+                      │  push to origin  │
+                      │  create PR (gh)  │
+                      └────────┬─────────┘
+                               │
+                      ┌──────────────────┐
+                      │  CLEANUP         │
+                      │  remove worktree │
+                      │  delete branch   │
+                      │  print PR URL    │
+                      └──────────────────┘
+```
+
+### Findings
+
+The review step returns structured findings with actions:
+
+| Action | Meaning | Who handles it |
+|---|---|---|
+| `no-op` | Informational | Silently accepted |
+| `auto-fix` | Mechanical fix (typos, dead code, missing error handling, behavioral changes) | Agent fixes automatically |
+
+### Worktree isolation
+
+By default kaizen creates a git worktree for each run. Your working directory stays clean while the agent operates in isolation. The worktree is removed after the run completes.
+
+```
+my-project/                    ← your tree, untouched
+  .kaizen/worktrees/<slug>/    ← agent works here
+```
+
+The opencode server starts in the main repo directory; individual sessions point at the worktree. This lets opencode see the full project context while the agent modifies only the isolated branch.
+
+### Iteration memory
+
+The work phase uses a `notes.md` file to carry context across iterations. Each iteration the agent reads prior notes, does one incremental piece of work, and appends its summary. Failed iterations still record learnings.
+
+## Configuration
+
+`~/.kaizen/config.json` (created automatically on first run):
+
+```json
+{
+  "max_work_iterations": null,
+  "max_review_rounds": 3,
+  "max_consecutive_failures": 3,
+  "opencode_bin": "opencode",
+  "use_worktree": true,
+  "server_url": null
+}
+```
+
+### Shared server
+
+By default each kaizen run spawns its own `opencode serve` process. For batch work, start a server once and reuse it across runs:
+
+```bash
+opencode serve --hostname 127.0.0.1 --port 4096 &
+kaizen "fix issue #1" --server-url http://127.0.0.1:4096
+kaizen "fix issue #2" --server-url http://127.0.0.1:4096
+```
+
+Or set it in config: `"server_url": "http://127.0.0.1:4096"`.
+
+When `--server-url` is set, kaizen skips server startup/teardown — it creates and destroys sessions on the existing server instead.
+
+**Checking for an existing server.** To find any running opencode servers on the machine (the TUI and `opencode serve` both start one):
+
+```bash
+pgrep -a opencode
+```
+
+To check a specific port (e.g. the default `4096`):
+
+```bash
+curl -sf http://127.0.0.1:4096/global/health
+```
+
+A `200` response means a server is running and ready. Note: the TUI starts its own internal server on a random port (unless overridden with `--port`).
+
+**Closing the server.** When you're done, stop the background process:
+
+```bash
+kill %1          # if launched with & in the current shell
+```
+
+Or send `POST /instance/dispose` to shut the server down cleanly over HTTP:
+
+```bash
+curl -X POST http://127.0.0.1:4096/instance/dispose
+```
+
+Note: the TUI runs its own server internally — disposing it will also close the TUI. Only shut down a server you started yourself.
+
+## Project structure
+
+```
+src/kaizen/
+  agent.py            # opencode HTTP server integration
+  git.py              # git operations
+  config.py           # ~/.kaizen/config.json
+  run.py              # run state + notes
+  orchestrator.py     # work iteration loop
+  work_prompt.py      # iteration prompt builder
+  findings.py         # finding types and action classification
+  review_prompt.py    # review + fix prompt builders
+  loop.py             # coordinates work → review → fix → ship
+  cli.py              # CLI entry point
+  steps/              # review, push, pr
+```
+
+## License
+
+MIT

kaizen_loop-0.1.0/justfile

@@ -0,0 +1,17 @@
+build:
+    pip install -e .
+
+test:
+    python -m pytest
+
+lint:
+    python -m ruff check src/
+
+fmt:
+    python -m ruff format src/
+
+clean:
+    rm -rf build/ dist/ *.egg-info src/*.egg-info
+
+run *ARGS:
+    python -m kaizen {{ARGS}}

kaizen_loop-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kaizen-loop"
+version = "0.1.0"
+description = "Continuous code improvement: autonomous work → review → fix → ship"
+requires-python = ">=3.10"
+license = "MIT"
+
+[project.optional-dependencies]
+dev = ["pytest", "ruff"]
+
+[project.scripts]
+kaizen = "kaizen.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kaizen"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

kaizen_loop-0.1.0/src/kaizen/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

kaizen_loop-0.1.0/src/kaizen/__main__.py

@@ -0,0 +1,4 @@
+from kaizen.cli import main
+
+if __name__ == "__main__":
+    main()

kaizen_loop-0.1.0/src/kaizen/agent.py

@@ -0,0 +1,349 @@
+import http.client
+import json
+import os
+import signal
+import socket
+import subprocess
+import time
+from contextlib import contextmanager
+from dataclasses import dataclass
+from urllib.parse import quote, urlparse
+
+_RETRYABLE_STATUS = frozenset({502, 503, 504})
+_MAX_RETRIES = 2
+_RETRY_BASE_DELAY = 0.5
+
+
+def _validate_server_url(url: str | None) -> None:
+    if url is None:
+        return
+    parsed = urlparse(url)
+    if parsed.scheme not in ("http", "https"):
+        raise ValueError(
+            f"Invalid server URL: {url!r}. Must start with http:// or https://"
+        )
+    if not parsed.hostname:
+        raise ValueError(f"Invalid server URL: {url!r}. No hostname found.")
+
+
+@dataclass
+class AgentResult:
+    output: dict
+    text: str = ""
+    input_tokens: int = 0
+    output_tokens: int = 0
+
+
+class _Session:
+    def __init__(self, agent: "OpenCodeAgent", session_id: str):
+        self._agent = agent
+        self._id = session_id
+
+    @property
+    def id(self) -> str:
+        return self._id
+
+    def send(self, prompt: str, schema: dict | None = None) -> AgentResult:
+        try:
+            return self._agent._send_message(self._id, prompt, schema)
+        except Exception:
+            self._agent._abort_session(self._id)
+            raise
+
+
+class OpenCodeAgent:
+    def __init__(self, bin_path: str = "opencode", server_url: str | None = None):
+        _validate_server_url(server_url)
+        self.bin_path = bin_path
+        self._external_server = server_url
+        self._process: subprocess.Popen | None = None
+        self._base_url: str | None = server_url
+        self._port: int | None = None
+        self._conn: http.client.HTTPConnection | None = None
+
+    def _get_conn(self) -> http.client.HTTPConnection:
+        if self._conn is not None:
+            return self._conn
+        url = self._base_url
+        if not url:
+            raise RuntimeError("No server URL configured")
+        parsed = urlparse(url)
+        self._conn = http.client.HTTPConnection(
+            parsed.hostname or "127.0.0.1",
+            parsed.port or 80,
+            timeout=300,
+        )
+        return self._conn
+
+    def _reconnect(self) -> http.client.HTTPConnection:
+        self._close_conn()
+        return self._get_conn()
+
+    def _close_conn(self) -> None:
+        if self._conn:
+            try:
+                self._conn.close()
+            except Exception:
+                pass
+            self._conn = None
+
+    def _http_request(
+        self,
+        method: str,
+        path: str,
+        body: dict | None = None,
+        timeout: float | None = None,
+        max_retries: int = _MAX_RETRIES,
+    ) -> dict:
+        conn = self._get_conn()
+        if timeout is not None:
+            conn.timeout = timeout
+        headers = {"Accept": "application/json"}
+        data = None
+        if body is not None:
+            data = json.dumps(body).encode()
+            headers["Content-Type"] = "application/json"
+
+        last_err: Exception | None = None
+        for attempt in range(max_retries + 1):
+            try:
+                conn.request(method, path, body=data, headers=headers)
+                resp = conn.getresponse()
+                resp_data = resp.read()
+                if 200 <= resp.status < 300:
+                    return json.loads(resp_data)
+                if resp.status in _RETRYABLE_STATUS and attempt < max_retries:
+                    last_err = RuntimeError(f"HTTP {resp.status}")
+                    time.sleep(_RETRY_BASE_DELAY * (2**attempt))
+                    conn = self._reconnect()
+                    continue
+                raise RuntimeError(
+                    f"HTTP {resp.status}: {resp_data.decode(errors='replace')}"
+                )
+            except (
+                ConnectionError,
+                OSError,
+                http.client.HTTPException,
+            ) as e:
+                if attempt < max_retries:
+                    last_err = e
+                    time.sleep(_RETRY_BASE_DELAY * (2**attempt))
+                    conn = self._reconnect()
+                    continue
+                raise RuntimeError(
+                    f"Request failed after {max_retries} retries: {e}"
+                ) from e
+        raise last_err  # type: ignore[misc]
+
+    def _request(
+        self,
+        path: str,
+        method: str = "GET",
+        body: dict | None = None,
+        timeout: float = 300,
+    ) -> dict:
+        return self._http_request(method, path, body=body, timeout=timeout)
+
+    def _ensure_server(self, server_cwd: str) -> None:
+        if self._base_url:
+            self._check_external_server()
+            return
+
+        self._port = _get_free_port()
+        env = {**os.environ}
+        env.pop("OPENCODE_SERVER_USERNAME", None)
+        env.pop("OPENCODE_SERVER_PASSWORD", None)
+
+        self._process = subprocess.Popen(
+            [
+                self.bin_path,
+                "serve",
+                "--hostname",
+                "127.0.0.1",
+                "--port",
+                str(self._port),
+                "--print-logs",
+            ],
+            cwd=server_cwd,
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            env=env,
+            start_new_session=True,
+        )
+        self._base_url = f"http://127.0.0.1:{self._port}"
+        self._wait_healthy(timeout=30)
+
+    def _check_external_server(self) -> None:
+        url = self._base_url
+        if not url:
+            raise RuntimeError("No server URL configured")
+        try:
+            self._http_request(
+                "GET", "/global/health", timeout=5, max_retries=1
+            )
+        except (
+            RuntimeError,
+            ConnectionError,
+            OSError,
+            http.client.HTTPException,
+        ) as e:
+            port = url.split(":")[-1].rstrip("/")
+            raise RuntimeError(
+                f"Shared server at {url} is not reachable. "
+                f"Start it with: opencode serve --hostname 127.0.0.1 --port {port}  |  Error: {e}"
+            )
+
+    def _wait_healthy(self, timeout: float = 30) -> None:
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            if self._process and self._process.poll() is not None:
+                raise RuntimeError("opencode server exited during startup")
+            try:
+                conn = self._reconnect()
+                conn.timeout = 2
+                conn.request("GET", "/global/health")
+                resp = conn.getresponse()
+                resp.read()
+                if resp.status == 200:
+                    return
+            except (ConnectionError, OSError, http.client.HTTPException):
+                pass
+            time.sleep(0.25)
+        raise RuntimeError(
+            f"opencode server did not become healthy on port {self._port}"
+        )
+
+    def _create_session(self, session_dir: str) -> str:
+        resp = self._request(
+            f"/session?directory={quote(session_dir, safe='')}",
+            method="POST",
+            body={},
+            timeout=10,
+        )
+        return resp.get("id", "")
+
+    @contextmanager
+    def session(self, work_dir: str, repo_dir: str | None = None):
+        server_cwd = repo_dir or work_dir
+        self._ensure_server(server_cwd)
+        session_id = self._create_session(work_dir)
+        try:
+            yield _Session(self, session_id)
+        finally:
+            self._delete_session(session_id)
+
+    def run(
+        self,
+        prompt: str,
+        work_dir: str,
+        schema: dict | None = None,
+        repo_dir: str | None = None,
+    ) -> AgentResult:
+        server_cwd = repo_dir or work_dir
+        self._ensure_server(server_cwd)
+        session_id = self._create_session(work_dir)
+        try:
+            return self._send_message(session_id, prompt, schema)
+        except Exception:
+            self._abort_session(session_id)
+            raise
+        finally:
+            self._delete_session(session_id)
+
+    def _send_message(
+        self, session_id: str, prompt: str, schema: dict | None = None
+    ) -> AgentResult:
+        body: dict = {
+            "role": "user",
+            "parts": [{"type": "text", "text": prompt}],
+        }
+        if schema:
+            body["format"] = {
+                "type": "json_schema",
+                "schema": schema,
+                "retryCount": 1,
+            }
+        result = self._request(
+            f"/session/{session_id}/message",
+            method="POST",
+            body=body,
+            timeout=600,
+        )
+
+        info = result.get("info", {})
+        structured = info.get("structured")
+        tokens = info.get("tokens", {})
+
+        if structured:
+            return AgentResult(
+                output=structured,
+                input_tokens=tokens.get("input", 0),
+                output_tokens=tokens.get("output", 0),
+            )
+
+        text = ""
+        for part in result.get("parts", []):
+            if part.get("type") == "text" and part.get("text"):
+                text = part["text"]
+
+        if not text:
+            raise RuntimeError("No structured output or text in agent response")
+
+        raise RuntimeError(f"Agent returned unstructured text: {text[:200]}")
+
+    def _abort_session(self, session_id: str) -> None:
+        try:
+            self._request(
+                f"/session/{session_id}/abort", method="POST", timeout=3
+            )
+        except Exception:
+            pass
+
+    def _delete_session(self, session_id: str) -> None:
+        try:
+            self._request(
+                f"/session/{session_id}", method="DELETE", timeout=3
+            )
+        except Exception:
+            pass
+
+    def close(self) -> None:
+        if self._external_server:
+            self._close_conn()
+            return
+        if self._base_url:
+            try:
+                self._http_request(
+                    "POST", "/instance/dispose", timeout=5, max_retries=0
+                )
+            except Exception:
+                pass
+        self._close_conn()
+        if self._process and self._process.poll() is None:
+            try:
+                self._process.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                try:
+                    os.killpg(os.getpgid(self._process.pid), signal.SIGTERM)
+                except OSError:
+                    self._process.terminate()
+                try:
+                    self._process.wait(timeout=5)
+                except subprocess.TimeoutExpired:
+                    try:
+                        os.killpg(
+                            os.getpgid(self._process.pid), signal.SIGKILL
+                        )
+                    except OSError:
+                        self._process.kill()
+                    self._process.wait(timeout=2)
+        self._process = None
+        self._base_url = None
+        self._port = None
+
+
+def _get_free_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]