dev-autopilot 0.4.0__tar.gz

dev_autopilot-0.4.0/LICENSE

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

dev_autopilot-0.4.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: dev-autopilot
+Version: 0.4.0
+Summary: Autopilot builds your software project while you are away. You write what you want in plain words and start it once. You get working software, tested, with a record of every step.
+License: MIT
+Project-URL: Homepage, https://github.com/manishjnv/AutoPilot
+Project-URL: Documentation, https://github.com/manishjnv/AutoPilot#readme
+Project-URL: Changelog, https://github.com/manishjnv/AutoPilot/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/manishjnv/AutoPilot/issues
+Keywords: autonomous,coding-agent,claude-code,developer-tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Provides-Extra: aws
+Requires-Dist: boto3>=1.26; extra == "aws"
+Dynamic: license-file
+
+# Autopilot
+
+Autopilot builds your software project while you are away. You write what you want in plain words and start it once. You get working software, tested, with a record of every step.
+It is for one developer, or for a person with an idea and a developer friend.
+
+**Give it a plan tonight. Wake up to a working app, and proof that it works.** Claude Code (the coding agent) writes the code; Python code decides when a task is complete.
+
+[![CI](https://github.com/manishjnv/AutoPilot/actions/workflows/ci.yml/badge.svg)](https://github.com/manishjnv/AutoPilot/actions/workflows/ci.yml)
+![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+## Claude Code alone and with Autopilot
+
+| | Claude Code alone | With Autopilot |
+|---|---|---|
+| Direction | Claude can choose the design as it works. | Your plan sets the design. The gate refuses plan changes. |
+| Checks | The model can say that work is done. | Autopilot runs your build, lint and test commands. A task merges only if they pass. |
+| Failures | You find and repair a problem. | A stronger model tries again. Autopilot repairs a missing tool or a red main branch. |
+| Questions | The chat waits for you. | That task waits. Other tasks continue. |
+| Status | You scroll the chat. | `ap watch` shows tasks, output, progress and usage. |
+
+The [full comparison](ARCHITECTURE.md#13-claude-code-alone-and-with-autopilot) has ten rows. Use Claude Code alone
+for a small change, a question, or an open design.
+
+## How it works
+
+![The loop: plan, task, Claude Code session, the gate, then main. Work that fails goes back to a stronger model.](assets/loop.gif)
+
+```mermaid
+flowchart LR
+    accTitle: How Autopilot builds a plan
+    accDescr: Each task runs in a new Claude Code session. Python runs the checks. A pass merges to main, a fail retries on a stronger model, and a blocked task becomes a question while the other tasks continue. At the end, a completion audit adds tasks for gaps.
+    plan["Plan"] --> task["Next task"]
+    task --> session["New Claude Code<br/>session"]
+    session --> gate{"Python runs<br/>the checks"}
+    gate -->|pass| merge["Merge to main"]
+    gate -->|fail| retry["Retry on a<br/>stronger model"]
+    retry --> session
+    retry -->|blocked| park["Question in NEEDS-YOU.md,<br/>build the other tasks"]
+    park --> task
+    merge --> task
+    merge -->|plan done| audit{"Completion<br/>audit"}
+    audit -->|gaps| task
+    audit -->|complete| app["Working app"]
+```
+
+## Follow the build
+
+`ap watch` shows the build in the terminal; the status page shows the same data in your browser (sample data).
+
+![The terminal window of the watch command: panels for the project, the tasks, the live output, the progress, the usage, the files and the issues.](assets/dashboard-terminal.png)
+
+![The status page in the browser: the question for you at the top, then the same panels as the terminal window.](assets/dashboard-browser.png)
+
+## Real results
+
+Two real projects built from a plan:
+
+- **SecretScan** finds leaked secrets in a repository.
+- **envguard** checks `.env` files against a schema and finds secrets in the git history.
+
+| Measure | SecretScan | envguard |
+|---|---|---|
+| Tasks merged | **27 of 27**: 13 from the plan, 14 from the audits | **21 of 21**: 11 from the plan, 10 from the audits |
+| Blocked tasks | **0** | **0** |
+| Passed on the first attempt | 25 of 27 | 17 of 21 |
+| Decisions that needed a person | **0** | **0** |
+| Agent time | 2.2 hours, 38 sessions | 1.4 hours, 42 sessions |
+| Cost at API prices | $17.13 | $19.01 |
+
+Both runs used a subscription. The envguard audits found 8 real bugs; Autopilot fixed all. envguard is private; numbers come from the run log. A lean rerun of envguard used 39.5 percent fewer tokens per task.
+
+## Install
+
+One line. It installs what is missing for your user, with no administrator prompt.
+Windows (PowerShell):
+
+```powershell
+irm https://raw.githubusercontent.com/manishjnv/AutoPilot/main/install.ps1 | iex
+```
+
+macOS, Linux or WSL:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/manishjnv/AutoPilot/main/install.sh | bash
+```
+
+On Windows pick Windows or WSL, not both; WSL only for the sandbox. With [uv](https://docs.astral.sh/uv/) already
+installed, `uv tool install dev-autopilot` is the same.
+Open a project folder and type `ap`. The first run logs you in to Claude (a paid plan, Pro or Max), then starts.
+See [What `ap` does](HOWTO.md#what-ap-does-in-a-folder). After a release, run `ap upgrade`. For a repair or a
+second machine, run `ap install`. Checksums and each step: [Install with one script](HOWTO.md#install-with-one-script).
+
+## Example output
+
+Shortened real output:
+
+```text
+task P02-T01 attempt 1 failed: PROBLEM: skip/focus marker added in tests/test_walker.py
+session #10 task P02-T01 model=sonnet attempt=2
+task P02-T01 done (sonnet, $0.39)
+audit: completion audit: 92% complete, 8 corrective tasks (FIX001)
+```
+
+## Documentation
+
+| To | Read |
+|---|---|
+| Build your first project | [Tutorial](GUIDE.md) |
+| Do one job: a server, phone alerts, an existing project | [How-to guides](HOWTO.md) |
+| Look up a command, setting, file or term | [Reference](REFERENCE.md) |
+| How Autopilot works and why | [Architecture](ARCHITECTURE.md) |
+
+## Good to know
+
+> [!WARNING]
+> Use a sandbox on a server: sessions run without permission prompts. See
+> [Run Autopilot on a server](HOWTO.md#run-autopilot-on-a-server).
+
+- Version 0.3.0, an early release. [MIT license](LICENSE).
+- One CLI agent per session. See [limits and runners](HOWTO.md#limits-and-supported-agent-clis).

dev_autopilot-0.4.0/README.md

@@ -0,0 +1,121 @@
+# Autopilot
+
+Autopilot builds your software project while you are away. You write what you want in plain words and start it once. You get working software, tested, with a record of every step.
+It is for one developer, or for a person with an idea and a developer friend.
+
+**Give it a plan tonight. Wake up to a working app, and proof that it works.** Claude Code (the coding agent) writes the code; Python code decides when a task is complete.
+
+[![CI](https://github.com/manishjnv/AutoPilot/actions/workflows/ci.yml/badge.svg)](https://github.com/manishjnv/AutoPilot/actions/workflows/ci.yml)
+![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+## Claude Code alone and with Autopilot
+
+| | Claude Code alone | With Autopilot |
+|---|---|---|
+| Direction | Claude can choose the design as it works. | Your plan sets the design. The gate refuses plan changes. |
+| Checks | The model can say that work is done. | Autopilot runs your build, lint and test commands. A task merges only if they pass. |
+| Failures | You find and repair a problem. | A stronger model tries again. Autopilot repairs a missing tool or a red main branch. |
+| Questions | The chat waits for you. | That task waits. Other tasks continue. |
+| Status | You scroll the chat. | `ap watch` shows tasks, output, progress and usage. |
+
+The [full comparison](ARCHITECTURE.md#13-claude-code-alone-and-with-autopilot) has ten rows. Use Claude Code alone
+for a small change, a question, or an open design.
+
+## How it works
+
+![The loop: plan, task, Claude Code session, the gate, then main. Work that fails goes back to a stronger model.](assets/loop.gif)
+
+```mermaid
+flowchart LR
+    accTitle: How Autopilot builds a plan
+    accDescr: Each task runs in a new Claude Code session. Python runs the checks. A pass merges to main, a fail retries on a stronger model, and a blocked task becomes a question while the other tasks continue. At the end, a completion audit adds tasks for gaps.
+    plan["Plan"] --> task["Next task"]
+    task --> session["New Claude Code<br/>session"]
+    session --> gate{"Python runs<br/>the checks"}
+    gate -->|pass| merge["Merge to main"]
+    gate -->|fail| retry["Retry on a<br/>stronger model"]
+    retry --> session
+    retry -->|blocked| park["Question in NEEDS-YOU.md,<br/>build the other tasks"]
+    park --> task
+    merge --> task
+    merge -->|plan done| audit{"Completion<br/>audit"}
+    audit -->|gaps| task
+    audit -->|complete| app["Working app"]
+```
+
+## Follow the build
+
+`ap watch` shows the build in the terminal; the status page shows the same data in your browser (sample data).
+
+![The terminal window of the watch command: panels for the project, the tasks, the live output, the progress, the usage, the files and the issues.](assets/dashboard-terminal.png)
+
+![The status page in the browser: the question for you at the top, then the same panels as the terminal window.](assets/dashboard-browser.png)
+
+## Real results
+
+Two real projects built from a plan:
+
+- **SecretScan** finds leaked secrets in a repository.
+- **envguard** checks `.env` files against a schema and finds secrets in the git history.
+
+| Measure | SecretScan | envguard |
+|---|---|---|
+| Tasks merged | **27 of 27**: 13 from the plan, 14 from the audits | **21 of 21**: 11 from the plan, 10 from the audits |
+| Blocked tasks | **0** | **0** |
+| Passed on the first attempt | 25 of 27 | 17 of 21 |
+| Decisions that needed a person | **0** | **0** |
+| Agent time | 2.2 hours, 38 sessions | 1.4 hours, 42 sessions |
+| Cost at API prices | $17.13 | $19.01 |
+
+Both runs used a subscription. The envguard audits found 8 real bugs; Autopilot fixed all. envguard is private; numbers come from the run log. A lean rerun of envguard used 39.5 percent fewer tokens per task.
+
+## Install
+
+One line. It installs what is missing for your user, with no administrator prompt.
+Windows (PowerShell):
+
+```powershell
+irm https://raw.githubusercontent.com/manishjnv/AutoPilot/main/install.ps1 | iex
+```
+
+macOS, Linux or WSL:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/manishjnv/AutoPilot/main/install.sh | bash
+```
+
+On Windows pick Windows or WSL, not both; WSL only for the sandbox. With [uv](https://docs.astral.sh/uv/) already
+installed, `uv tool install dev-autopilot` is the same.
+Open a project folder and type `ap`. The first run logs you in to Claude (a paid plan, Pro or Max), then starts.
+See [What `ap` does](HOWTO.md#what-ap-does-in-a-folder). After a release, run `ap upgrade`. For a repair or a
+second machine, run `ap install`. Checksums and each step: [Install with one script](HOWTO.md#install-with-one-script).
+
+## Example output
+
+Shortened real output:
+
+```text
+task P02-T01 attempt 1 failed: PROBLEM: skip/focus marker added in tests/test_walker.py
+session #10 task P02-T01 model=sonnet attempt=2
+task P02-T01 done (sonnet, $0.39)
+audit: completion audit: 92% complete, 8 corrective tasks (FIX001)
+```
+
+## Documentation
+
+| To | Read |
+|---|---|
+| Build your first project | [Tutorial](GUIDE.md) |
+| Do one job: a server, phone alerts, an existing project | [How-to guides](HOWTO.md) |
+| Look up a command, setting, file or term | [Reference](REFERENCE.md) |
+| How Autopilot works and why | [Architecture](ARCHITECTURE.md) |
+
+## Good to know
+
+> [!WARNING]
+> Use a sandbox on a server: sessions run without permission prompts. See
+> [Run Autopilot on a server](HOWTO.md#run-autopilot-on-a-server).
+
+- Version 0.3.0, an early release. [MIT license](LICENSE).
+- One CLI agent per session. See [limits and runners](HOWTO.md#limits-and-supported-agent-clis).

dev_autopilot-0.4.0/autopilot/__init__.py

@@ -0,0 +1,4 @@
+"""Autopilot — autonomous, plan-driven development orchestrator for Claude Code."""
+
+__version__ = "0.4.0"
+AGENT_DIR = ".agent"

dev_autopilot-0.4.0/autopilot/__main__.py

@@ -0,0 +1,6 @@
+"""`python -m autopilot`: works even when the `autopilot` command is not on PATH."""
+import sys
+
+from .cli import main
+
+sys.exit(main())

dev_autopilot-0.4.0/autopilot/backends/__init__.py

@@ -0,0 +1,159 @@
+"""Agent backends. Each runs ONE fresh session and returns a SessionResult."""
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
+
+# Anchored to a line start: the CLI prints these as its own message, so prose inside a failed session doesn't count.
+LIMIT_RX = re.compile(r"^\s*(?:you've|you have) hit your (?:[\w-]+ ){0,3}limit"
+                      r"(?:\s*[·•|\-–—,.]*\s*resets?\s+(?P<reset>[^\n]+))?", re.I | re.M)
+API_LIMIT_RX = re.compile(r"^\s*API Error: (?:429|529)\b|^\s*API Error:.*(?:rate_limit_error|overloaded_error)", re.I | re.M)
+_RESET_RX = re.compile(r"^(?:(?P<mon>[a-z]{3,9})\.?\s+(?P<day>\d{1,2})\s*(?:,|at)?\s*)?(?P<h>\d{1,2})(?::(?P<m>\d{2}))?"
+                       r"\s*(?P<ap>am|pm)?\s*(?:\((?P<tz>[^)]+)\))?$", re.I)
+_MONTHS = {m: i + 1 for i, m in enumerate("jan feb mar apr may jun jul aug sep oct nov dec".split())}
+
+
+def parse_reset(s: str, now: datetime) -> float | None:
+    """Next future occurrence of a CLI reset time like `3:45pm`, `Oct 3, 9am (Asia/Calcutta)`; None if unparseable."""
+    try:
+        m = _RESET_RX.match((s or "").strip().rstrip(".").strip())
+        if not m or not (m["ap"] or m["m"]):
+            return None
+        tz = now.tzinfo
+        if m["tz"]:
+            try:
+                from zoneinfo import ZoneInfo
+                tz = ZoneInfo(m["tz"].strip())
+            except Exception:  # noqa: BLE001  no tzdata / unknown zone: fall back to local time
+                pass
+        if now.tzinfo:
+            now = now.astimezone(tz)
+        h, mi = int(m["h"]), int(m["m"] or 0)
+        if m["ap"]:
+            if not 1 <= h <= 12:
+                return None
+            h = h % 12 + (12 if m["ap"].lower() == "pm" else 0)
+        if m["mon"]:
+            mon = _MONTHS.get(m["mon"][:3].lower())
+            if not mon:
+                return None
+            t = now.replace(month=mon, day=int(m["day"]), hour=h, minute=mi, second=0, microsecond=0)
+            if t <= now:
+                t = t.replace(year=t.year + 1)
+        else:
+            t = now.replace(hour=h, minute=mi, second=0, microsecond=0)
+            if t <= now:
+                t += timedelta(days=1)
+        return t.timestamp()
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def detect_limit(text: str, now: datetime | None = None) -> tuple[bool, float | None]:
+    """(limited, reset_at epoch). Only the CLI's subscription message or API 429/529 errors count, never agent prose."""
+    text = text or ""
+    m = LIMIT_RX.search(text)
+    if m:
+        return True, (parse_reset(m["reset"], now or datetime.now().astimezone()) if m["reset"] else None)
+    return bool(API_LIMIT_RX.search(text)), None
+
+
+# Failures of the machinery, not of the work: retried by the orchestrator, never counted as a task attempt.
+# Anchored to a line start like LIMIT_RX, so the agent's own prose about these words never counts.
+_AUTH_RX = re.compile(r"^\s*(?:Invalid API key|Please run /login|OAuth token (?:has )?expired|API Error: 401\b)",
+                      re.I | re.M)
+# Node's own error shapes ("reason: getaddrinfo ENOTFOUND", "Error: connect ECONNREFUSED"), not a bare code in prose
+_NET_RX = re.compile(r"^\s*API Error: (?:Connection error|Request timed out|50[0234]\b)|"
+                     r"(?:reason:|Error:)\s+(?:getaddrinfo |connect |read |write )?"
+                     r"(?:ENOTFOUND|ECONNREFUSED|ECONNRESET|ETIMEDOUT|EAI_AGAIN)\b", re.I | re.M)
+
+
+def detect_infra(text: str) -> str:
+    """'auth' (not logged in / key rejected), 'network' (connection, timeout, server 5xx) or ''."""
+    text = text or ""
+    return "auth" if _AUTH_RX.search(text) else "network" if _NET_RX.search(text) else ""
+
+
+@dataclass
+class SessionRequest:
+    prompt: str
+    model: str
+    cwd: str
+    timeout_sec: int = 3600
+    budget_usd: float | None = None
+    system_append: str = ""
+    read_only: bool = False
+    log_path: str = ""
+    resume: str = ""                                        # continue this CLI session instead of starting fresh
+    resume_totals: dict = field(default_factory=dict)       # that session's totals so far (see SessionResult.totals)
+    schema: dict | None = None                              # JSON Schema of the final report (schemas.REPORTS)
+    effort: str = ""                                        # overrides agent.effort for this session
+    web_only: bool = False                                  # research: only web search/fetch and reading files
+    mcp_config: str = ""                                    # MCP servers for this session only (e.g. Playwright)
+    no_tools: bool = False                                  # triage of untrusted text: no file, shell, web or MCP tools
+    label: str = ""                                         # live progress lines: "P01-T01 Project skeleton [haiku]"
+    on_context: object = None                               # J5: called with the session's context size (tokens)
+    on_tokens: object = None                                # G8: called with the session's running token total
+
+
+@dataclass
+class SessionResult:
+    ok: bool
+    text: str = ""
+    cost: float = 0.0
+    session_id: str = ""
+    report: dict = field(default_factory=dict)
+    error: str = ""
+    rate_limited: bool = False
+    reset_at: float | None = None
+    timed_out: bool = False
+    stuck: bool = False                          # killed for repeating the same action (stream-json watch)
+    usage: dict = field(default_factory=dict)   # model -> {input, output, cache_read, cache_write, cost}
+    num_turns: int = 0
+    duration_ms: int = 0
+    totals: dict = field(default_factory=dict)  # whole-session {cost, usage, num_turns, duration_ms}, for a later resume
+    infra: str = ""                              # 'cli' | 'auth' | 'network': the machinery failed, not the work
+    window: dict = field(default_factory=dict)  # G1: the CLI's own usage figure {five_hour: {pct, reset}, seven_day, status}
+    config: dict = field(default_factory=dict)  # I1: what the session loaded from the user's Claude config (names, counts)
+
+
+def since(totals: dict, base: dict) -> dict:
+    """A resumed CLI session reports whole-session totals; keep only what this run added (never below zero)."""
+    def sub(a, b):
+        return max(0, (a or 0) - (b or 0))
+    bu = base.get("usage") or {}
+    usage = {m: {k: sub(v, (bu.get(m) or {}).get(k)) for k, v in u.items()} for m, u in (totals.get("usage") or {}).items()}
+    return {"cost": sub(totals.get("cost"), base.get("cost")), "usage": usage,
+            "num_turns": sub(totals.get("num_turns"), base.get("num_turns")),
+            "duration_ms": sub(totals.get("duration_ms"), base.get("duration_ms"))}
+
+
+def parse_report(text: str) -> dict:
+    """Extract the last ```json block (or bare JSON object) from the agent's final message."""
+    blocks = re.findall(r"```(?:json)?\s*(\{.*?\})\s*```", text or "", re.S)
+    candidates = list(reversed(blocks))
+    if not candidates:
+        m = re.search(r"(\{[^{}]*\"status\".*\})\s*$", text or "", re.S)
+        if m:
+            candidates = [m.group(1)]
+    for c in candidates:
+        try:
+            data = json.loads(c)
+            if isinstance(data, dict):
+                return data
+        except json.JSONDecodeError:
+            continue
+    return {}
+
+
+def get_backend(cfg):
+    kind = cfg.get("agent.backend", "claude_cli")
+    if kind == "claude_cli":
+        from .claude_cli import ClaudeCLIBackend
+        return ClaudeCLIBackend(cfg)
+    if kind == "command":
+        from .command import CommandBackend
+        return CommandBackend(cfg)
+    raise ValueError(f"unknown backend {kind}")