Metadata-Version: 2.4
Name: keshro
Version: 0.1.42
Summary: High-stakes engineering project execution for AI coding agents
Project-URL: Homepage, https://keshro.com
Project-URL: Repository, https://github.com/jlewitt1/keshro-cli
Project-URL: Documentation, https://keshro.com/developers
Author-email: Josh Lewittes <josh.lewittes@gmail.com>
License: MIT
License-File: LICENSE
Keywords: ai-agents,cli,coding-agents,execution,planning
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.11
Requires-Dist: graphifyy>=0.3.0
Requires-Dist: httpx-sse>=0.4
Requires-Dist: httpx>=0.28
Requires-Dist: rich>=13.0
Requires-Dist: textual>=0.80
Requires-Dist: typer>=0.9
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=1.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# Keshro

Plan and run high-stakes engineering projects with AI agents.

```bash
keshro login              # authenticate and install Claude Code + Codex integrations
keshro create             # scan project, create the right migration/project
keshro continue           # agents execute in parallel if possible
```

`keshro login` authenticates the CLI and installs agent integrations on the current machine. For Codex, Keshro adds a managed block to `~/.codex/AGENTS.md` and preserves any non-Keshro content already in that file.

Keshro is built for migrations first. It scans the repo, asks the follow-up questions that actually matter for the migration, creates the right migration or project, then coordinates agents to execute it safely.

Works with your existing coding agent. Use Claude Code or Codex for planning, migration intake, and parallel execution.

Examples:
- AWS Batch -> Airflow
- Terraform -> Pulumi
- Jenkins -> GitHub Actions
- Express -> Fastify
- Apache Iceberg -> ClickHouse

What Keshro does:
1. Builds a migration-aware execution context with risks, open questions, task ordering, and acceptance criteria
2. Runs agents in parallel in isolated git worktrees
3. Detects live file overlap in Codex worktrees, pauses the lagging agent, and resumes after rebasing onto the winning task's changes
4. Carries learnings from one task into related future tasks
5. Tracks progress, decisions, rollback points, and live per-agent telemetry through execution

## Create a migration or project

```bash
keshro create
```

Keshro scans the project, detects whether this is a migration, asks the follow-up questions that matter, and creates the right migration or project with a linked execution context.

If Keshro stops to ask follow-up questions in `/keshro` or another agent session, surface those questions back to the user and resume with the generated `--answers-file` command instead of building a giant shell command by hand.

## Execute

Keshro drives the full execution loop — picks up the next task, gives the agent context, validates the result, marks it done, and moves to the next one. You don't manage it.

```bash
keshro continue
```

By default, `keshro continue` runs the next ready wave in parallel when the environment supports it. Each launched agent gets its own session ID and heartbeats live status back to Keshro, including touched files, progress messages, recent errors, and mid-task conflict detection. Use `--no-parallel` only when you explicitly want one task at a time.

### Executors

Each task in a plan runs on an *executor* — the runtime that actually executes it. Two executors ship today:

- **`local_claude_code`** (default) — a local Claude Code subprocess running inside an isolated git worktree on your machine.
- **`managed_agent`** — Anthropic's hosted Claude Managed Agents (the `managed-agents-2026-04-01` beta). Runs the task in a hosted cloud container instead of a local subprocess.

  **Setup:** create an Agent and Environment in the Anthropic console, then paste the IDs into **Account → Managed Agents** (personal) or **Workspace settings** (shared). Personal config overrides workspace. Sessions run against your own Anthropic account.

  **Responsibility split:** Keshro routes the task and mounts your repo with your GitHub token. Your Anthropic Environment owns everything else — tools, dependencies, secrets, network access. Tasks that depend on local-only files, private VPN reachability, or custom local toolchains are not portable to the managed executor; keep those on `local_claude_code`.

The executor is resolved per task in this order: `--executor` flag → `task.executor` (set per-task in the plan view) → personal default → workspace default → `local_claude_code` as the safe fallback.

```bash
keshro continue --executor local_claude_code   # Force every task in this run onto local Claude Code
keshro continue --executor managed_agent       # Force every task onto Anthropic Managed Agents
keshro continue --executor local               # Friendly alias
keshro continue --executor managed             # Friendly alias
```

If a task was marked done too early, reopen it with `keshro task reopen <task-id> -p <plan-id>`. That clears any stale blocker and moves it back to `todo` by default, or you can pass `--status in_progress` to resume work immediately.

## Monitor

```bash
keshro status
```

## Saved team + cost context

Keshro reuses team size, seniority mix, and blended cost defaults across migrations and plans so you don't re-enter them each time. Context is scoped to the active org or your personal account.

```bash
keshro org context                  # Show saved team + cost context for the active org
keshro org context --clear-team     # Forget saved org team context
keshro org context --clear-cost     # Forget saved org cost context
keshro org context --clear-all      # Forget both

keshro user context                 # Same, but for your personal account
keshro user context --clear-all     # Clear personal team + cost context
```

## Works with

Planning, execution, and parallel mode work with [Claude Code](https://claude.ai/code) and [Codex](https://openai.com/index/introducing-codex/). Both agents run in isolated git worktrees during parallel mode. If one agent is rate-limited, Keshro suggests switching and supports a saved default via `keshro config set --agent ...`.

Cursor is supported for in-editor context via `.cursorrules` (`keshro setup-cursor`), but does not have a headless CLI, so it cannot be used as an execution agent.

Keshro can also create general projects from repos, issues, and freeform descriptions, but the primary workflow is migrations.

## License

MIT
