crystl's north star

This is crystl's NORTH-STAR.md, a document that agents must abide by when working on crystl. The rejected ideas and the current focus are left off this public version because they change over time. Any project can keep one: see NORTH-STAR.md.

What it is for

crystl is a multitasking terminal for running many agents at once. Its job is to make people better at working with agents, and with each other.

It is built for people who direct more than one agent, and for the people learning from and teaching one another through that work. A feature belongs in crystl when it makes that shared work easier to see, to trust, or to direct.

Five questions

Every feature has to make at least one of these questions faster or more trustworthy to answer:

What was done? A record of finished work that you can find and point to later.

What is being done? An honest view of every agent that is running, at a glance. See the agent activity panel.

What will be done? The plan: queued tasks, schedules, and what you intend next. See the workbench and schedules.

Who did it, and at what cost? The agent, the model, the tokens and the time, so you can learn which setup works. See token tracking.

How is this project set up? What the project is for, what kind of work happens in it, and what is missing, with safe ways for you or your agent to fix real gaps. See the project optimizer.

A feature that answers none of the five is not built.

Rules that hold across every feature

One surface for you and your agent. Everything works from the app and from the CLI, through the same path. An agent can do the work for you, but you never need one to get something done.

Never less than a normal terminal. crystl adds visibility and control. It never stops you doing something you could do in Terminal.app, unless you turned that block on yourself.

Only you move you. No agent can switch the project or session you are looking at. An agent that needs your attention asks with a floating card, and you decide when to look.

Every failure says why. An error, a refusal or a block names what happened and what to do next, for a person on screen and for an agent in its terminal. Nothing quietly does nothing and reports success.

Unknown is never reported as fine. When crystl can't tell, it says so and says why. For example, unfinished work lists only what it could check, and says which projects it couldn't ask.

Agent-neutral. Any CLI agent runs in crystl. History and records work across agents, not for one vendor only.

Your bug is our bug. When something breaks while crystl is being built, the first question is whether it can break for you. If it can, fixing it for you is the work.

What crystl is not

A feature that answers none of the five questions, or doesn't help you work with agents or with other people, is out of scope. That rules out a terminal theme marketplace, setup screens that don't help a real project, and history that only works for one agent.