Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 88 additions & 0 deletions .github/workflows/readme-install.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
name: readme install

# Runs each README's Install block AS WRITTEN, one line per job, then runs the command it installed.
# The install lines are read out of the README, never copied into this file, so a README edit is
# what gets tested. Runs on a README change, weekly (the registry and the runtimes move under a
# README that did not), and by hand.

on:
pull_request:
paths:
- README.md
- packages/aitm/README.md
- .github/workflows/readme-install.yml
push:
branches: [main]
paths:
- README.md
- packages/aitm/README.md
- .github/workflows/readme-install.yml
schedule:
- cron: '23 6 * * 1'
workflow_dispatch:

concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true

permissions:
contents: read

jobs:
install:
name: ${{ matrix.readme }} · ${{ matrix.runtime.label }}
runs-on: ubuntu-22.04
timeout-minutes: 10
strategy:
fail-fast: false
matrix:
readme: [README.md, packages/aitm/README.md]
# The floors the READMEs state (Node 20, Deno 2.0), plus current Deno 2.x: Deno's install
# flags are what changed under the README last time.
runtime:
- { label: npm on Node 20, tool: npm, node: '20' }
- { label: bun on Node 20, tool: bun, node: '20' }
- { label: deno 2.0.0, tool: deno, deno: '2.0.0' }
- { label: deno 2.x, tool: deno, deno: '2.x' }
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7

# A bun-installed aitm runs on Node (its bin is `#!/usr/bin/env node`), so the bun job gets
# the Node floor too: the README tells the reader Node must be on PATH.
- if: matrix.runtime.tool != 'deno'
uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7
with:
node-version: ${{ matrix.runtime.node }}

- if: matrix.runtime.tool == 'bun'
uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
with:
bun-version: latest

- if: matrix.runtime.tool == 'deno'
uses: denoland/setup-deno@22d081ff2d3a40755e97629de92e3bcbfa7cf2ed # v2.0.5
with:
deno-version: ${{ matrix.runtime.deno }}

- name: global bin directories on PATH
run: |
echo "$HOME/.bun/bin" >> "$GITHUB_PATH"
echo "$HOME/.deno/bin" >> "$GITHUB_PATH"

- name: run the README's ${{ matrix.runtime.tool }} install line
env:
README: ${{ matrix.readme }}
TOOL: ${{ matrix.runtime.tool }}
run: |
# The Install block is the first fenced block under the "Install" heading.
block=$(awk '/^## .*Install/ { h = 1; next } h && /^```/ { if (b) exit; b = 1; next } b' "$README")
line=$(printf '%s\n' "$block" | grep -E "^${TOOL} +install " || true)
if [ "$(printf '%s' "$line" | grep -c .)" -ne 1 ]; then
echo "::error file=$README::expected exactly one '$TOOL install' line in the Install block, found: ${line:-none}"
exit 1
fi
echo "+ $line"
eval "$line"

- name: the installed command runs
run: aitm --version
33 changes: 19 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,8 @@ Give `aitm` a sentence, walk away, come back to a stack of merged pull requests.
> **Inspired by** [`developerz-ai/claude-task-master`](https://github.com/developerz-ai/claude-task-master): same idea (a task-master that drives the work to merge), built here on the Vercel AI SDK + OpenRouter, provider-agnostic, with MCP client support and a much smaller surface area.

[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript&logoColor=white)](./packages/aitm/tsconfig.json)
[![Bun](https://img.shields.io/badge/Bun-≥1.1-fbf0df?logo=bun&logoColor=black)](https://bun.sh)
[![Node](https://img.shields.io/badge/Node-≥20-339933?logo=node.js&logoColor=white)](https://nodejs.org)
[![Deno](https://img.shields.io/badge/Deno-≥2.0-000000?logo=deno&logoColor=white)](https://deno.com)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)

---
Expand All @@ -32,12 +32,14 @@ No babysitting. No prompt-stuffing. No bespoke agent framework.
## ⚡ Install

```bash
bun install -g @developerz.ai/aitm # recommended for local dev
npm install -g @developerz.ai/aitm # works the same
deno install -A npm:@developerz.ai/aitm
bun install -g @developerz.ai/aitm # recommended for local dev
npm install -g @developerz.ai/aitm # works the same
deno install -g -A -n aitm npm:@developerz.ai/aitm # Deno 2
```

The package is scoped (`@developerz.ai/aitm`); the installed command is still `aitm`.
Installed with bun or npm, `aitm` runs on Node, so Node ≥ 20 must be on your `PATH` even when bun
did the install. Installed with deno, it runs on Deno ≥ 2.0.

Plain ESM + a `bun build --compile` single-file binary. No runtime lock-in.

Expand Down Expand Up @@ -110,7 +112,7 @@ same lifecycle lines are also appended to `.ai-task-master/progress.md`.

| Requirement | Note |
| --- | --- |
| 🟢 JS runtime | Bun ≥ 1.1, Node ≥ 20, or Deno ≥ 1.40. Bun preferred locally. |
| 🟢 JS runtime | Node ≥ 20 (whether bun or npm installed `aitm`), or Deno ≥ 2.0. Bun preferred for local dev. |
Comment thread
dinndev2 marked this conversation as resolved.
Resolved
| 🟣 `gh` CLI | authenticated against the target repo's remote |
| 📝 Agent config | `CLAUDE.md` or `AGENTS.md` at the target repo root |
| 🔑 Credentials | `OPENROUTER_API_KEY` env. That's it. |
Expand Down Expand Up @@ -230,18 +232,21 @@ Full walkthrough in [`docs/providers.md`](packages/aitm/docs/providers.md); prof
## 🧪 Try it on a sandbox repo

```bash
# 1. Clone a throwaway repo
git clone https://github.com/you/scratch && cd scratch
# 1. Create a throwaway repo (private, with a first commit) and clone it
gh repo create aitm-scratch --private --add-readme --clone && cd aitm-scratch

# 2. Drop a tiny CLAUDE.md so subagents know the style
echo "# CLAUDE.md\n- TypeScript strict.\n- No comments unless necessary." > CLAUDE.md
# 2. Commit a tiny CLAUDE.md so subagents know the style
printf '# CLAUDE.md\n\n- TypeScript strict.\n- No comments unless necessary.\n' > CLAUDE.md
git add CLAUDE.md && git commit -m "docs: add CLAUDE.md" && git push

# 3. Set your key and go
export OPENROUTER_API_KEY=sk-or-...
aitm start "add a /healthz endpoint with a test" --max-prs 1
```

A single PR opens, CI runs, it merges. Total wall-clock: a few minutes.
A single PR opens and merges. Total wall-clock: a few minutes. A new repository has no CI, so `aitm`
merges once it has confirmed there are no checks to wait for; add a workflow and it waits for green
first. Delete the repository afterwards with `gh repo delete aitm-scratch`.

## 📚 Docs

Expand All @@ -268,12 +273,12 @@ A single PR opens, CI runs, it merges. Total wall-clock: a few minutes.
PRs welcome. House style is in [`CLAUDE.md`](CLAUDE.md): SOLID, one responsibility per module, every module ships with a paired `*.test.ts`, no `any`, no default exports, conventional commits, no emoji in source.

```bash
bun install
bun test # unit + integration
bun run typecheck
bun run lint
bin/setup # bun install, then build the compat package a clean checkout lacks
bin/check # the gate, the same steps CI runs: typecheck, lint, import cycles, unit + integration tests
```

`bin/check` needs both Bun and Node on your `PATH` (CI uses Node 22).

## 📄 License

MIT.
8 changes: 5 additions & 3 deletions packages/aitm/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,10 +18,12 @@ baked in.
```bash
npm install -g @developerz.ai/aitm
bun install -g @developerz.ai/aitm
deno install -A npm:@developerz.ai/aitm
deno install -g -A -n aitm npm:@developerz.ai/aitm # Deno 2
```

The package is scoped; the installed command is just **`aitm`**.
The package is scoped; the installed command is just **`aitm`**. Installed with npm or bun, it runs
on Node ≥ 20 (so Node must be on your `PATH` even when bun did the install); installed with deno,
on Deno ≥ 2.0.

## 🚀 Quickstart

Expand Down Expand Up @@ -97,7 +99,7 @@ aitm config list

- `OPENROUTER_API_KEY` in the environment.
- The [`gh`](https://cli.github.com) CLI, authenticated (PRs, CI status, reviews).
- Node ≥ 20, Bun, or Deno ≥ 1.40 — ESM, no runtime lock-in.
- Node ≥ 20 (whether npm or bun installed `aitm`), or Deno ≥ 2.0 — ESM, no runtime lock-in.

## License

Expand Down