## Introduction

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](/content/docs/north-star/index.html).

## 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](/content/features/agent-activity-panel/index.html).

**What will be done?** The plan: queued tasks, schedules, and what you intend next. See the [workbench](/content/features/workbench/index.html) and [schedules](/content/features/schedule-agents/index.html).

**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](/content/features/token-tracking/index.html).

**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](/content/features/project-optimizer/index.html).

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](/content/docs/cli/index.html), 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](/content/features/floating-cards/index.html), 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](/content/docs/cli/#still-in-a-worktree-and-not-pushed/index.html) lists only what it could check, and says which projects it couldn't ask.

**Agent-neutral.** [Any CLI agent runs in `crystl`](/content/docs/faq/which-agents-does-crystl-work-with/index.html). 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.
