Using Jan Agent

Running jan with no subcommand opens the console. This is the main way to use Jan Agent.

The screen

Your own messages are the one filled block in the transcript: a full-width tinted bubble with a row of padding above and below, the text behind a ›. A /command or skill you invoke shows in the same bubble. The agent's answer starts with a dim • and the rest of it - code boxes and tables included - is indented under it. When the turn ends, a dim receipt lines up under the answer: Worked for 12s • 14:02 • ↑ 43K ↓ 1.1K • 45.6/s - the duration, the time it finished (with the date when it was not today, Oct 7 14:02), context sent, tokens produced, and throughput when there was output to measure.

Notes from Jan itself carry a glyph in the left column: • for information, a yellow ⚠ for a warning, and a red ■ for an error, so a failure stands out even without colour.

Tool rows fold to one line each: a • bullet, then the verb and what it acted on (Ran cargo test, Edited src/cli.rs). The bullet's colour is the call's state: it pulses while the call runs, then turns green when it succeeds, red when it fails, and yellow when the turn was cancelled before it finished. A result or diff hangs off the row beneath a dim └. Ctrl+O expands them all, or click a row to expand just that one. Once the answer arrives, the tool calls before it fold into a single • Worked · N steps row.

Calls that only look around - reading files, listing directories, searching, reading memory notes or skills - share one row, • Exploring while any is in flight and • Explored once they finish, with one line per action beneath it: Read cli.rs, main.rs (consecutive reads merge, and a file gets its full path only when another one shares its name), Search version in src, List docs. A search that matched nothing says (no matches); a call that failed adds a red (failed) and the row's header counts them: • Explored · 1 failed. Past four actions the rest fold into … +N more, which Ctrl+O opens up along with each call's output. A run that mixes in anything else (a command, a web search) keeps a counted summary such as • Read 2 files; ran 1 command.

A shell command shows as • Running cargo test (12s), with its output streaming in beneath it as it prints - the newest five lines, under a dim … +N earlier lines count once there are more. A command of several lines shows its next two on a dim │ rail, then a count of the rest. When it finishes the row reads • Ran cargo test, followed by the first three lines of output and … +N lines (Ctrl-O to expand); a silent command shows (no output), and a failed one adds its exit code: • Ran cargo test (exit 101).

An edit names its size on the row - • Edited src/cli.rs (+3 -1), or Created and Wrote for a new or rewritten file - and the diff follows it, indented, with each line's number in a dim column on the left. Added and removed lines are tinted green and red; on a 16-colour terminal the text takes the colour instead. A dim ⋮ separates hunks that are not adjacent.

A turn

You type, the agent works, and it stops when it has an answer or needs you.

While it runs, each tool call appears as it happens. A large write previews the file as it streams in, so you can see what's being produced before it lands. Esc cancels the turn.

Type while it's working and your message queues rather than being dropped - see Sessions.

The working row

While a turn runs, the input row shows an action word that turns over every few seconds, with a brightness sweep crossing it, so a long turn does not read as a hung UI. After the word comes the key that cancels it, Esc; the turn's elapsed time (12s, 1m 05s, 1h 02m) is in the header. On a narrow terminal the row drops the long hint first, then the short one, so it always stays one line.

Waiting on background work

When the agent has answered but a subagent it dispatched or a monitor it started is still going, the turn stays open and waits for it. The header badge reads ○ [waiting] ([watching] while a monitor is up), and the input row says what the turn is waiting on, with each item under it:

A single subagent is named on the row itself (• Waiting for review). At most three items are listed, the last ending in … when there are more. The row does not animate, since nothing is being generated, and it shows no elapsed time: that stays in the header. The footer reads Esc stop: Esc stops the background work and ends the turn. Anything you type steers the agent.

A subagent that finishes during the wait leaves its • Finished NAME row below the answer, and the agent picks up from there.

Monitors and background shells

A monitor that matches leaves a ◔ Monitor mon-1: 'build' matched row; one that times out leaves a ⚠ warning instead. When a command the agent sent to the background ends, it leaves a tool row (• Background command finished after 12s: make build), or a ⚠ warning if it failed. If the dock has no room for every monitor, its last row reads +N more · /monitors. /monitors lists all of them, and x stops the selected one.

While commands run in the background, a dim row sits above the input:

During a turn the row is hidden so the input area keeps its height, and the working row ends with · 2 bg shells instead. /shells lists the commands; x stops one, and /stop stops all of them.

Motion

The working row and the [thinking] badge animate: a brightness sweep crosses the label. A running tool row pulses its bullet the same way. The sweep changes colour only, never width, so nothing beside it moves. It is skipped on a 16-colour terminal, which has no shades in between to sweep through.

To hold everything still, set this in ~/.jan/config.toml:

Throbbers then show a static •, a running tool's bullet stays dim, and every label keeps its resting colour. Jan also turns animations off at launch when the OS asks for reduced motion: on macOS (System Settings > Accessibility > Display > Reduce motion) and on GNOME-family Linux desktops (animations off). Windows is not detected yet, so use the key there. Restart Jan after changing either.

The prompt-cache hit rate

Providers cache the front of a request, so a turn that reuses it costs a fraction of a cold one. The header carries the share of this session's prompt tokens that came from the cache:

The segment appears only once a route has reported a cache field: a route that reports nothing shows no badge at all, rather than a fabricated 0%. A rate that reads 0% is drawn in red, because a prefix rewritten every turn and never read is the state worth interrupting for. After a resumed or forked history the badge adds (this process), since the counters begin where this process did.

/context carries the full numbers - a session total and the last request's sample - see Context and compaction.

Reasoning

While a model works it may emit a chain of thought before it lands on an answer. By default the console folds that reasoning into a summary row instead of dumping it into the transcript. The header shows where it is: [thinking] while a reasoning block streams, then [thought for Ns] once it closes. With folding on, an open block also streams its last few lines into the live tail, so you can watch the thought form without pushing the answer off the screen.

Ctrl+O expands every folded reasoning block, or click a row to expand just that one.

Two knobs in agent.toml and two in ~/.jan/config.toml tune this:

See Project config for the agent.toml keys.

Questions

The agent can use the ask tool when it needs your choice before it keeps working. The console stops the run and shows a question with options; one option may be marked as recommended.

By default a question waits forever for your answer. To keep unattended or long-running runs from stalling when nobody is at the terminal, set ask_timeout_secs in ~/.jan/config.toml, or edit the same row in /settings:

When the value is N, an unanswered question auto-resolves after N seconds. Jan chooses the recommended option when the question has one, otherwise the first option. The auto choice is always one of the listed options, not the UI-only custom answer. 0 or an unset key means wait forever, which is the default.

Timed-out answers are marked in the tool result with NOTE [ask_timeout], so the agent can tell they were auto-selected instead of typed by you.

This does not apply to the tool-permission prompts from jan --safe; those never auto-approve. See Approving work and Tool permissions.

Approving work

Writes and shell commands are auto-approved. Start the console with jan --safe and they stop to ask instead:

You see a diff for a file change, or the exact command for a shell call. Full detail in Tool permissions.

Getting help

/help inside the console prints every command and keybinding. / alone filters the command list as you type.

Next