codemate-team 0.1.0__tar.gz

codemate_team-0.1.0/LICENSE

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

codemate_team-0.1.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: codemate-team
+Version: 0.1.0
+Summary: A deterministic supervisor that runs Claude Code and Codex CLI through a Plan -> Implement -> Review -> Test workflow
+Author: Abhinav
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/abhinav-18max/codemate
+Project-URL: Repository, https://github.com/abhinav-18max/codemate
+Project-URL: Issues, https://github.com/abhinav-18max/codemate/issues
+Keywords: ai,agents,claude,codex,cli,developer-tools,automation,code-review
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# codemate
+
+`codemate` is a sequential AI development team runner.
+
+It does not replace Codex CLI or Claude Code. It supervises them:
+
+```text
+Plan -> Implement -> Review -> Test
+```
+
+The CLI owns sequencing, git state, run artifacts, local test execution, and
+policy checks. Agent CLIs only receive one bounded role at a time.
+
+## Install
+
+The PyPI distribution is `codemate-team`; it installs a `codemate` command.
+
+As a global CLI tool (recommended):
+
+```bash
+uv tool install codemate-team
+# or: pipx install codemate-team
+codemate --help
+```
+
+Run once without installing:
+
+```bash
+uvx --from codemate-team codemate --help
+```
+
+For local development from a checkout:
+
+```bash
+uv run --with-editable . codemate --help
+```
+
+## Quick Start
+
+Initialize a repo:
+
+```bash
+codemate init
+```
+
+Review and edit `team.yml`, then check local prerequisites:
+
+```bash
+codemate doctor
+```
+
+Run a task:
+
+```bash
+codemate run "Fix the flaky checkout test"
+```
+
+Inspect results:
+
+```bash
+codemate status
+codemate logs --step implement
+codemate diff
+```
+
+Accept or reset:
+
+```bash
+codemate accept --commit --message "Fix flaky checkout test"
+codemate reset
+```
+
+## Generated Project Files
+
+`codemate init` creates:
+
+```text
+team.yml
+.team/
+  prompts/
+  schemas/
+  runs/
+docs/
+  team.md
+```
+
+`.team/runs/` and `.team/lock.json` are ignored so run artifacts do not pollute
+normal source control status.
+
+## Safety Model
+
+- The default config requires a clean worktree before a run starts.
+- A run uses a branch under `ai/team/<run-id>`.
+- Agent writes are checked against `policies.allow_paths` and
+  `policies.deny_paths`.
+- Local command output is recorded by the CLI.
+- Agent claims about tests are ignored; configured commands are the authority.
+- Fix loops are bounded by `limits.max_fix_retries`.
+- The CLI never pushes or merges by default.
+
+## Documentation
+
+- [Overview](docs/README.md)
+- [Architecture](docs/architecture.md)
+- [Commands](docs/commands.md)
+- [Configuration](docs/configuration.md)
+- [Safety](docs/safety.md)

codemate_team-0.1.0/README.md

@@ -0,0 +1,107 @@
+# codemate
+
+`codemate` is a sequential AI development team runner.
+
+It does not replace Codex CLI or Claude Code. It supervises them:
+
+```text
+Plan -> Implement -> Review -> Test
+```
+
+The CLI owns sequencing, git state, run artifacts, local test execution, and
+policy checks. Agent CLIs only receive one bounded role at a time.
+
+## Install
+
+The PyPI distribution is `codemate-team`; it installs a `codemate` command.
+
+As a global CLI tool (recommended):
+
+```bash
+uv tool install codemate-team
+# or: pipx install codemate-team
+codemate --help
+```
+
+Run once without installing:
+
+```bash
+uvx --from codemate-team codemate --help
+```
+
+For local development from a checkout:
+
+```bash
+uv run --with-editable . codemate --help
+```
+
+## Quick Start
+
+Initialize a repo:
+
+```bash
+codemate init
+```
+
+Review and edit `team.yml`, then check local prerequisites:
+
+```bash
+codemate doctor
+```
+
+Run a task:
+
+```bash
+codemate run "Fix the flaky checkout test"
+```
+
+Inspect results:
+
+```bash
+codemate status
+codemate logs --step implement
+codemate diff
+```
+
+Accept or reset:
+
+```bash
+codemate accept --commit --message "Fix flaky checkout test"
+codemate reset
+```
+
+## Generated Project Files
+
+`codemate init` creates:
+
+```text
+team.yml
+.team/
+  prompts/
+  schemas/
+  runs/
+docs/
+  team.md
+```
+
+`.team/runs/` and `.team/lock.json` are ignored so run artifacts do not pollute
+normal source control status.
+
+## Safety Model
+
+- The default config requires a clean worktree before a run starts.
+- A run uses a branch under `ai/team/<run-id>`.
+- Agent writes are checked against `policies.allow_paths` and
+  `policies.deny_paths`.
+- Local command output is recorded by the CLI.
+- Agent claims about tests are ignored; configured commands are the authority.
+- Fix loops are bounded by `limits.max_fix_retries`.
+- The CLI never pushes or merges by default.
+
+## Documentation
+
+- [Overview](docs/README.md)
+- [Architecture](docs/architecture.md)
+- [Commands](docs/commands.md)
+- [Configuration](docs/configuration.md)
+- [Safety](docs/safety.md)

codemate_team-0.1.0/codemate/__init__.py

@@ -0,0 +1,3 @@
+"""Codemate sequential AI team runner."""
+
+__version__ = "0.1.0"

codemate_team-0.1.0/codemate/agents.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True)
+class AgentRunInput:
+    run_id: str
+    step_id: str
+    cwd: Path
+    prompt: str
+    mode: str
+    expected_output: str
+    output_path: Path
+    raw_log_path: Path
+    schema_path: Path | None
+    config: dict[str, Any]
+
+
+@dataclass(frozen=True)
+class AgentRunResult:
+    ok: bool
+    output_path: Path
+    raw_log_path: Path
+    exit_code: int
+
+
+class AgentAdapter:
+    def run(self, input: AgentRunInput) -> AgentRunResult:
+        raise NotImplementedError
+
+
+class CodexCliAdapter(AgentAdapter):
+    def run(self, input: AgentRunInput) -> AgentRunResult:
+        command = str(input.config.get("command", "codex"))
+        _require_executable(command)
+        args = [
+            command,
+            "exec",
+            "--cd",
+            str(input.cwd),
+            "--sandbox",
+            str(input.config.get("sandbox", "workspace-write")),
+            "--ask-for-approval",
+            str(input.config.get("approval", "never")),
+            "--output-last-message",
+            str(input.output_path),
+        ]
+        if input.schema_path and input.schema_path.exists():
+            args.extend(["--output-schema", str(input.schema_path)])
+        args.append(input.prompt)
+        return _run_process(args, input)
+
+
+class ClaudeCodeAdapter(AgentAdapter):
+    def run(self, input: AgentRunInput) -> AgentRunResult:
+        command = str(input.config.get("command", "claude"))
+        _require_executable(command)
+        permission_mode = _claude_permission_mode(input.mode, input.config)
+        output_format = str(input.config.get("output_format", "text"))
+        args = [command, "-p", input.prompt, "--permission-mode", permission_mode]
+        if output_format != "text":
+            args.extend(["--output-format", output_format])
+        result = _run_process(args, input)
+        # Claude Code streams its final answer to stdout (captured in the raw log)
+        # rather than to a dedicated output file, so derive the output ourselves.
+        if not input.output_path.read_text(errors="replace").strip():
+            raw = input.raw_log_path.read_text(errors="replace")
+            input.output_path.write_text(_extract_claude_message(raw, output_format))
+        return result
+
+
+def adapter_for(config: dict[str, Any]) -> AgentAdapter:
+    provider = str(config.get("provider", "")).lower()
+    if provider == "codex-cli":
+        return CodexCliAdapter()
+    if provider == "claude-code":
+        return ClaudeCodeAdapter()
+    raise ValueError(f"Unsupported agent provider: {provider}")
+
+
+def _extract_claude_message(raw: str, output_format: str) -> str:
+    """Pull the assistant's final message out of captured Claude Code output.
+
+    With `--output-format json` the CLI emits a result envelope; extract its
+    `result` field. Anything else (including malformed JSON) falls back to the
+    raw captured text so no output is ever silently dropped.
+    """
+    if output_format == "json":
+        try:
+            data = json.loads(raw.strip() or "{}")
+        except json.JSONDecodeError:
+            return raw
+        if isinstance(data, dict) and isinstance(data.get("result"), str):
+            return data["result"]
+    return raw
+
+
+def _claude_permission_mode(mode: str, config: dict[str, Any]) -> str:
+    if mode in {"read_only", "review_only"}:
+        return "plan"
+    if mode == "write":
+        return str(config.get("write_permission_mode", "acceptEdits"))
+    return str(config.get("default_mode", "plan"))
+
+
+def _run_process(args: list[str], input: AgentRunInput) -> AgentRunResult:
+    timeout = int(input.config.get("timeout_seconds", 900))
+    with input.raw_log_path.open("w") as raw_log:
+        try:
+            result = subprocess.run(
+                args,
+                cwd=input.cwd,
+                text=True,
+                stdout=raw_log,
+                stderr=subprocess.STDOUT,
+                timeout=timeout,
+                check=False,
+            )
+            exit_code = result.returncode
+        except subprocess.TimeoutExpired:
+            raw_log.write(f"\n[timeout after {timeout} seconds]\n")
+            exit_code = 124
+    if not input.output_path.exists():
+        input.output_path.write_text("")
+    return AgentRunResult(
+        ok=exit_code == 0,
+        output_path=input.output_path,
+        raw_log_path=input.raw_log_path,
+        exit_code=exit_code,
+    )
+
+
+def _require_executable(command: str) -> None:
+    if shutil.which(command) is None:
+        raise FileNotFoundError(f"Required agent command not found: {command}")

codemate_team-0.1.0/codemate/artifacts.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+
+def new_run_id() -> str:
+    return datetime.now().strftime("%Y-%m-%dT%H-%M-%S-%f")
+
+
+def latest_run_dir(root: Path) -> Path:
+    runs = root / ".team" / "runs"
+    candidates = sorted([path for path in runs.glob("*") if path.is_dir()])
+    if not candidates:
+        raise FileNotFoundError("No runs found")
+    return candidates[-1]
+
+
+@dataclass
+class RunState:
+    run_id: str
+    task: str
+    flow: str
+    status: str
+    branch: str
+    base_branch: str
+    base_head: str
+    current_step: str | None = None
+    steps: list[dict[str, Any]] = field(default_factory=list)
+    changed_files: list[str] = field(default_factory=list)
+    reason: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "run_id": self.run_id,
+            "task": self.task,
+            "flow": self.flow,
+            "status": self.status,
+            "branch": self.branch,
+            "base_branch": self.base_branch,
+            "base_head": self.base_head,
+            "current_step": self.current_step,
+            "steps": self.steps,
+            "changed_files": self.changed_files,
+            "reason": self.reason,
+        }
+
+    @classmethod
+    def from_path(cls, path: Path) -> "RunState":
+        data = json.loads(path.read_text())
+        return cls(**data)
+
+
+class RunArtifacts:
+    def __init__(self, root: Path, run_id: str) -> None:
+        self.root = root
+        self.run_id = run_id
+        self.dir = root / ".team" / "runs" / run_id
+        self.dir.mkdir(parents=True, exist_ok=True)
+
+    @property
+    def state_path(self) -> Path:
+        return self.dir / "state.json"
+
+    def write_state(self, state: RunState) -> None:
+        self.state_path.write_text(json.dumps(state.to_dict(), indent=2) + "\n")
+
+    def write_text(self, name: str, content: str) -> Path:
+        path = self.dir / name
+        path.write_text(content)
+        return path
+
+    def read_text(self, name: str, default: str = "") -> str:
+        path = self.dir / name
+        return path.read_text() if path.exists() else default
+
+
+class RunLock:
+    def __init__(self, root: Path, run_id: str) -> None:
+        self.path = root / ".team" / "lock.json"
+        self.run_id = run_id
+
+    def __enter__(self) -> "RunLock":
+        if self.path.exists():
+            if self._is_stale():
+                self.path.unlink()
+            else:
+                raise RuntimeError(f"Another codemate run appears active: {self.path}")
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.path.write_text(
+            json.dumps(
+                {
+                    "run_id": self.run_id,
+                    "pid": os.getpid(),
+                    "created_at": datetime.now().isoformat(timespec="seconds"),
+                },
+                indent=2,
+            )
+            + "\n"
+        )
+        return self
+
+    def _is_stale(self) -> bool:
+        try:
+            data = json.loads(self.path.read_text())
+        except (OSError, json.JSONDecodeError):
+            return False
+        pid = data.get("pid")
+        if not isinstance(pid, int) or pid <= 0:
+            return False
+        try:
+            os.kill(pid, 0)
+        except ProcessLookupError:
+            return True
+        except PermissionError:
+            return False
+        return False
+
+    def __exit__(self, _exc_type: object, _exc: object, _tb: object) -> None:
+        if self.path.exists():
+            self.path.unlink()