A harness around Claude Code that runs your tasks on
your machine — code, writing, actions, posts.
Write the ticket on Ponos's own board — the console, or a folder of Markdown files. He
brings back a pull request, a text, an action carried out or a post ready to go. You answer
in a word, even from your phone, and nothing ships until you say yes. Notion, GitHub,
Telegram, Slack and OpenRouter plug in when you want them; none of them is required.
▶ Ponos in a minute — one ticket, from Ready to Done. The video plays on the site, sound on.
The name is a robot's, after the Greek god of toil: he does the tedious part of a ticket in
your place, and you keep the decisions. The repository, the ponos command, the Python
package and every path on your machine carry his name too. An installation from before the
rename moves over on its own — see the CHANGELOG for what it does.
The loop, in four gestures
Two of them are yours, and each takes a few seconds. The two in between are Ponos's.
- You write the ticket — what you would tell a colleague, on your board — then you
move it to Ready.
- Ponos does it while you do something else: a pull request on its own branch, a text
written into the ticket, an action carried out.
- You read, and answer in a word. A question or a result reaches you — in the
console, or on your phone. oui is a whole answer.
- He delivers. Move it to Validated: the pull request is merged, the post is
published — and only then is it Done.
Three things it does that a to-do list does not
- It asks first — a doubt stops it. A ticket nobody typed is classified before it
runs, and a hesitation sends it back to you with the question. An action stops at its
first doubt — a wrong account, a value the ticket does not give — rather than act on a
guess. See The type of a ticket.
- You keep the hand — nothing goes out without you. No pull request is merged and
nothing is published until you move the ticket to Validated. And it all runs on your
machine, each ticket in a disposable worktree — your own checkout is never touched. See
What protects your code.
- It comes to you — “oui” is enough. When a ticket needs a decision, the question
reaches you on Telegram or Slack, and your reply lands on the ticket. See
Being told, and answering with one word.
Not only code — four kinds of task. The ticket's type decides the road: pick it, or let
a small model read the ticket and choose.
| Type | A ticket | What comes back |
|---|
| Code | Console: limit the Done column | A pull request, on its own branch and a disposable worktree; the tests run. Merged when you validate. |
| Writing | Draft the October newsletter | A text, written into the ticket, ready to copy. No repository needed. |
| External action | Add the DNS records for the new domain | Done in the browser or a service's settings, with every change logged. It stops at its first doubt. |
| Publication | Post the 1.2 release on LinkedIn | Prepared and shown to you first. Published once you say yes. |
Tickets also come back on their own on a schedule, and the
console's chat is a Claude Code session in your workspace.
A board of its own
Ponos needs nobody else's board. The console, on 127.0.0.1, is where
you write a ticket, drag it to Ready and watch its session live. Under it, the board is
a folder of Markdown files: grep, your
editor and git read it too.
Everything runs on your machine; the board, GitHub and your channel are the only things it
reaches — see Architecture.
Plugs in where you already work. If you want.
Ponos needs Claude Code and nothing else. Each of these is one more token in the settings,
and none of them is a requirement.
| Optional | |
|---|
| Your board in Notion. | Tickets, projects and schedules become Notion databases, and every report is written back on the ticket's page. The Notion side |
| GitHub | Pull requests. | A code ticket comes back as one, through a GitHub App, an access token or gh, and is merged on your yes. Writing, actions and posts need none of it. Several GitHub accounts |
| Telegram · Slack | Your phone. | A question or a result reaches you there, and your answer — oui will do — lands on the ticket. Telegram and Slack |
| OpenRouter | Every other model. | One key: a GPT writes the copy, a model transcribes a voice note — or the sessions themselves run on the model you name. Every other model |
Install it
One command. It checks what your machine has — Python, git, Claude Code and its sign-in, room
on the disk —, names whatever is missing with the command that installs it, starts Ponos and
opens its console in your browser. Beyond Claude Code, nothing to sign up for.
curl -LsSf https://raw.githubusercontent.com/hermez-agency/ponos/main/install.sh | sh
Everything after that happens in the console, on http://127.0.0.1:8787 — never on the
Internet: a first connection in steps, each one checked against the
real thing before the next. The language; the password that opens the console; who answers
the sessions; Notion — paste the integration's token, add it to one page, and the board is
built under that page, found on its own as soon as it is shared; GitHub in one click; a first
project; and a demonstration ticket, played there and then, which is the proof that every
step holds. No Notion? The board can be a folder of Markdown files.
It needs Linux or macOS, python3 ≥ 3.11 — what it imports, httpx and pydantic for the
runner and FastAPI and uvicorn for the console, goes into an environment of its own, made by the installer —,
git and Claude Code, which the installer offers to
install when it is missing. gh is optional: the console connects GitHub itself. What the
installer arms, how Ponos updates itself and every variable it reads are in
Installation; where it stops, and what to do, in
Troubleshooting.
Or in a container, on your machine or behind a domain: docker compose up -d, then the
console's first connection — see Docker. On Dokploy, a template does it in one
click: Install with Dokploy.
How a ticket travels
Notion Ponos what you get
────── ───────────── ────────────
Ready ──────▶ claims it, writes the session link
│
In progress ◀───────────┤
│
├─ has a repository ──▶ worktree, branch, commits
│ push + gh pr create ──▶ a pull request
│
└─ has none ──────────▶ scratch dir, ANSWER.md
published as Notion blocks ──▶ the page itself
In review ◀─────────── a pull request is waiting for you
Validated ──────▶ merges that pull request — or publishes what the
ticket holds: the post, the mail, the announcement
Done ◀─────────── once it is in
Which of the two you get is decided by the ticket's Type when it has one — Code,
Writing, External action, Publication — and otherwise by the project: a project that
names a repository produces code, a project that names none — or a ticket with no project
at all — produces a document. A ticket that reaches Ready with no type is classified
first, and a doubt stops it before anything runs. See The type of a ticket.
The documentation
The guide, one page per subject — its contents:
| Page | What it covers |
|---|
| Installation | what the installer arms, updating, the install variables, uninstalling |
| Configuration | Notion, config.toml, who answers the sessions, OpenRouter, GitHub, the vault |
| The board | the board as Markdown files, the Notion databases, the type, sub-type and model of a ticket |
| A ticket's life | the comments, the statuses, ten tickets on one repository, Validated, the tickets that come back |
| Telegram and Slack | being told, and answering with one word |
| The web console | the console, its first connection, signing in, connecting Ponos to Claude |
| Every command | the ponos command, its exit codes, and what clean removes |
| What protects your code | the worktrees, the permissions, what a session cannot touch |
| When the credits run out | waiting for the window, what a session may do alone, spending limits |
| On a server |
Working on Ponos itself — the architecture, the console's code, the tests, the mascot,
releases — is in CONTRIBUTING.md.
Author
Ponos is a Hermez product.
Licence
MIT.
