amaleh

Getting started

From a stable checkout to a first delegated run: what the machine needs, how the skill is installed, where credentials live, and the operations that start and resume a run.

1cloneclone the repo2doctorlocal check3installlinks skill dirs4preflightcredential + Jev5invoke /amalehstate the outcome6run state on disk.amaleh/ checkpoint7resumeinvoke again
The install and first-run sequence: clone https://github.com/mhamri/amaleh to a stable location you keep, then doctor, install and preflight prepare the machine and credential; invoking the skill starts a run that checkpoints to .amaleh and resumes when invoked again.

Prerequisites

  • Bun, or Node 24 or newer for the fallback launcher. The skill’s TypeScript CLI runs on either.
  • pi configured with OpenRouter, or OPENROUTER_API_KEY provided through your environment.
  • A git clone of the repository. Clone https://github.com/mhamri/amaleh to a stable location. Installation links the amaleh/ directory into your skill directories, so the checkout must stay in place afterwards.
  • No global package installation. The runtime has no npm runtime dependencies; installation only links the skill directories.

Install the skill

Clone the repository and run both operations from the checkout root, with Bun or with Node 24 or newer.

sh
git clone https://github.com/mhamri/amaleh
cd amaleh
bun amaleh/scripts/run.ts doctor
bun amaleh/scripts/run.ts install

doctor takes no run and changes nothing. install writes the skill links and refuses conflicting destinations; it never touches repository files or credentials.

Uninstall the skill

Run the uninstall operation from the checkout root to remove the skill links.

sh
bun amaleh/scripts/run.ts uninstall

uninstall removes the links install wrote into the Codex and Claude skill directories. It refuses conflicting targets — a real directory, a file, or a link that resolves elsewhere — and never touches the checkout.

Credentials and network

Use pi’s existing OpenRouter credential, or provide OPENROUTER_API_KEY through your environment. Never put credentials in the repository. Expired pi credentials are refreshed through pi.

Before the first OpenRouter operation in a session, run preflight through the same execution channel that will launch Jev and pi. It makes one bounded request with a ten-second timeout and validates the credential and the Jev response shape. It sends no project content, grants no permission, and changes no global setting.

sh
bun amaleh/scripts/run.ts preflight ./my-project my-run preflight.json
preflight.json
{ "network": "allowed", "channel": "pi" }

The input declares the host’s effective network status and the execution channel; an existing run is optional, and a fresh run id is enough. A result of ready means the credential and the Jev response shape were verified.

Network access and permission to send project context remain host-controlled. When the host reports restricted networking, request its supported network permission before making requests instead of spending retries in a blocked sandbox.

Your first run

Four steps take a checkout from unconfigured to a delegated, checkpointed run.

  1. 1

    Check the machine

    Run the doctor check. It is local: it reports the runtime engine and version, the platform, the pi executable it resolved, whether OpenRouter credentials were found, and the Jev endpoint. It does not prove network connectivity.

  2. 2

    Link the skill

    Run the install operation. It links amaleh/ into the current user’s Codex and Claude skill directories and refuses conflicting destinations, then leaves the checkout in place for the link to point at.

  3. 3

    Invoke the skill with your task

    Invoke /amaleh with the outcome you want. The skill handles discovery, planning, delegation, review and resume; you do not ask it which step comes next.

  4. 4

    Resume by invoking again

    A closed session is not a background scheduler. Invoking the skill again lists the workspace’s runs and resumes the one matching your request from its last checkpoint.

The same steps are available through the CLI. list returns one summary per run — id, status, intent, acceptance criteria and task count — so it is read before deciding what to do next. start takes host, model, intent, acceptance criteria and constraints from an input file, because structured values are never built by the shell.

sh
bun amaleh/scripts/run.ts list ./my-project
bun amaleh/scripts/run.ts start ./my-project my-first-run input.json

Next, read the workflow to see how a run moves from discovery to verified delivery, or go straight to the command reference.