Agent Sessions

An agent session is a durable record of one agent task. It keeps the prompt, the runs, the result, and the state across turns.

Overview

A Flint is an environment where agents run shard-based programs. Each run of an agent gets a session. The session tracks the work over time. The Mesh stores the notes and artifacts that the work produces.

Orbh manages sessions. It assigns each session a stable id. It records each run inside the session. This page covers sessions from the view of a Flint user. The Orbh docs cover session management in depth: see Sessions and Runs and Launching and Resuming Sessions.

Start an Interactive Session

flint orbh i starts an interactive agent session in the terminal. It opens the agent interface with session tracking.

flint orbh i
flint orbh i "Summarise the open tasks in this Flint."
flint orbh i claude "Review my notes."

The first argument is an optional runtime target. A target is runtime/profile, such as codex/a6h, or a bare runtime, such as claude. flint orbh profiles lists the profiles of each runtime. The next argument is an optional prompt. With no target, Orbh uses its default target list (see The Default Target List). With no prompt, the session starts empty.

Useful flags:

flint orbh i --continue <id>      # Continue a past session
flint orbh i --detached           # Start in the background and print the session id
flint orbh i --prompt-file ./prompt.md  # Read a long prompt from a file
flint orbh i --model <model>      # Override the model

flint orbh c picks a past session and continues it. flint orbh list --print shows the sessions of this Flint. flint orbh inspect <id> shows one session in detail.

Open a Session from Obsidian

flint obshn opens a new terminal tab in Obsidian and starts an interactive session there. It runs flint orbh i inside the new tab.

flint obshn "" "Review my notes."

The first argument is the Orbh profile target. An empty string lets Orbh select from its default target list. The second argument is an optional prompt. See Using Obsidian for the Obsidian setup.

The Default Target List

A command with no target (flint orbh i, flint orbh launch "<prompt>", flint orbh request "<prompt>") starts the first available target of the default target list. The list that Orbh ships:

1. claude/o55h: Claude Opus 5.5, high effort
2. codex/a6h: GPT-6 Astra, high effort

Before the session starts, the command prints the selected target and each skipped target with its reason:

claude/o55h skipped: claude is not installed
Target: codex/a6h (default list)

A target is available when its runtime CLI is installed, its profile exists, its account exists and has no active limit, and its login is not known to be expired. The skip reasons:

Only Claude has a local check of the login. An expired access token with a valid refresh token is not an expired login.

When no target is available, the command refuses with exit 1. It names the install command or the login command of the first target:

✘ No target of the default target list is available.
  claude/o55h skipped: claude is not installed
  codex/a6h skipped: codex is not installed
  Next: npm install -g @anthropic-ai/claude-code

The Three Layers

The highest layer that has a list applies. It replaces the lower list; the layers do not merge. The Flint layer in flint.toml:

[orbh]
default = ["codex/a6h", "claude/o55h"]

See Configuration for the [orbh] table and the Orbh settings file.

Show and Change the List

flint orbh profiles default                              # The list, its layer, the state of each target, and the selected target
flint orbh profiles default set codex/a6h claude/o55h    # Write the machine layer
flint orbh profiles default unset                        # Remove the machine layer
flint orbh profiles default set --flint claude/o55h      # Write the Flint layer of this Flint
flint orbh profiles default unset --flint                # Remove the Flint layer

Orbh Default Target List
  Layer:     shipped (the value that Orbh ships)
  Selected:  codex/a6h

  1. claude/o55h  ✘ claude is not installed
                  Next: npm install -g @anthropic-ai/claude-code
  2. codex/a6h    ✓ available

-p <dir> acts on the Flint at <dir>. --json prints one JSON value. unset names the list that applies after it.

Rules

• An explicit target never falls back. flint orbh i codex/a6h starts codex/a6h, or refuses: ✘ The target codex/a6h is not available: codex is not installed. An explicit target does not fall back.
• A bare runtime takes the first target of the list for that runtime: flint orbh i claude starts claude/o55h. When the list has no target of that runtime, the session starts with no profile.
• The account is checked. With --account <name>, Orbh checks the targets with that account. A session that a session of the same runtime starts is checked with the account of that session. An account never moves to another runtime.
• The selection is made once, when a session launches. A running session keeps its target. A resumed session keeps its target too.
• The agents of Orbh (flint orbh agent), the workers (flint orbh worker), the workflows (--target default, the default), and the NUU Flint plugin (an empty Orbh profile) use the list too.

Where Sessions Live

Session state lives in the .orb folder of the Flint. Current session spools live under:

.orb/spaces/local/spools/

These files are local session state. They are not published content of the Flint. The Flint-managed .gitignore excludes .orb.

What a Session Tracks

Each session tracks:

• a stable session id
• the runtime and profile that run it
• the mode (interactive, headless, or subagent)
• the launch prompt
• the working directory
• an optional title and description
• an optional parent session id
• one or more runs
• request and response records
• interface key and value state
• tracked artifact paths
• the result text

The work state shows where the session stands. The states are working, awaiting, needs-input, finished, and abandoned. needs-input means the session waits for an answer. awaiting means the session rests and expects follow-up.

One session can hold many runs. The session is the durable container. Each run is one concrete execution inside it. A resume adds a new run to the same session.

Sessions in Artifacts

Agents record their work in Mesh artifacts with two frontmatter fields.

The authors field names the people behind the artifact:

authors:
  - "[[@Nathan Luo]]"

The orbh-sessions field names the sessions that created or changed the artifact:

orbh-sessions:
  - "[[session-uuid-1]]"
  - "[[session-uuid-2]]"

Each entry is one Orbh session id in wiki link form. An agent appends its session id when it creates an artifact or edits it in a substantive way. All agent runtimes write to this one field.

Session Pins

Each session keeps a list of pinned Markdown files. Pins put the key files of the work first in the session finder. The agent pins a file when it starts work on it. It keeps the pin after the work ends.

Open the finder with Ctrl-] then o. It shows matching pins first in stored order. Other matches keep the usual ranking. A renamed file keeps its old pin path. The agent removes the old path and adds the new path after a rename.

The pin commands are agent commands:

flint helper pins add "Mesh/Notes/Design.md"
flint helper pins list
flint helper pins remove "Mesh/Notes/Design.md"

add appends paths and skips duplicates. list prints the pins as JSON. remove drops paths. Pins stay with the session across resume.

How an Agent Loads a Shard

An agent loads a shard before it uses the shard. It runs flint shard start and reads the shard init file:

flint shard start <ref>

The command prints a manifest. The manifest lists the init file, the required reading, the skills, the workflows, the templates, and the knowledge files. The agent reads the init file first. The init file defines what the shard does and how to use it.

In a headless session the agent runs flint shard hstart instead. It loads the headless init file in place of the interactive one. Headless workflows drop human review gates and report progress through session keys. See Shards for the shard model.

Sessions That a Schedule or a DM Starts

A Flint can start sessions by itself. A cron schedule of the module crons starts an agent session when it fires (flint module crons result <name> shows the last fire). A direct message to the Flint (flint module dms send) starts a session of the receiver Flint, and that session answers. Both need the module installed: flint module install @nuucognition/module/crons or @nuucognition/module/dms, then flint sync. A Flint-level value, such as a token, is not in the environment of a session: an agent reads it from flint.env.local or flint.env at the Flint root. See Modules, Crons, and DMs.

Repair Sessions

When a Flint command fails, its output ends with Or: flint fix. flint fix starts a repair session in the Computer Flint. The session reads the failure record and repairs the problem with the person.

flint fix          # Repair the last failure
flint fix --list   # List the failure records of this machine
flint fix 2        # Repair the second record of the list

flint fix starts an interactive session on the default target. flint doctor only checks the machine and starts no agent. To report the failure to NUU Cognition, run flint feedback --bug --with-failure. See Doctor and Fix for the full repair flow.

Related

• Using Obsidian
• Doctor and Fix
• Tutorial Agent Collaboration
• Modules, Crons, and DMs
• Shards
• Mesh
• Configuration
• CLI Commands
• Orbh