Ground a session

This tutorial builds the habit that pays across everything else on the platform: packaging the context for an effort once, so every agent session that touches it starts briefed instead of spending its first stretch re-discovering the project. You author a context artifact, attach a small knowledge graph to it, ground a live session with it, verify the grounding actually took, and iterate the artifact as the effort evolves.

The scenario: an effort that will outlive one session — say, a website revamp. It has a goal, a few decisions already made, a handful of files that matter, and it will be worked by you and by agents over days. Exactly the case where re-explaining yourself every session is the hidden cost.

Prerequisites

• The quickstart tour — you have opened Terminals and launched an agent pane before.
• The mental model: Context artifacts & grounding.
• A real effort with a few real files in your workspace — the tutorial works with placeholders, but the verification step is only convincing with content that means something to you.
• Costs: authoring and attaching cost nothing. The grounded session is an agent session on your Claude subscription. Graph depths have their own cost profile — stated at that step.

Step 1 — Author the artifact

Open Context Artifacts (sidebar ▸ Data) and create an artifact. Give it a clear name — sessions will be grounded with it by that name.

Work in Visual mode, the structured builder:

1. Write a one-line description and the freeform notes: the goal, the decisions already made, the constraints, the vocabulary. Write it as the briefing you would otherwise repeat.
2. Add file references — individual files or whole folders. You can also drag a file straight from your file manager onto the artifact.

You should see: edits save automatically as you type — there is no save button. Switch to Raw mode once to see what you actually built: the artifact is plain Markdown, nothing hidden behind the UI. It lives as a file under documents/context-artifacts/ in your workspace, which means your agents can read and even maintain it, and any outside edit shows up in the view automatically.

Step 2 — Attach a knowledge graph (optional, choose the depth)

Switch to KG mode to bundle a purpose-built graph with the artifact, built from its file references. Pick the build depth — the same three choices as everywhere in the platform:

Choose Structure only for this walk — it is a complete, useful state, not a stub, and it costs nothing. The choice is recorded on the artifact and tracks reality: enriching the graph later moves the badge on its own.

You should see: the attached graph appear in Cortex like any other workspace. The same documents stay single nodes in the one knowledge graph — attaching them here duplicates nothing.

Step 3 — Preview what the agent will receive

Before trusting the artifact with real work, open its preview: the exact materialized fragment a grounded session would be handed — notes, resolved file references, and graph pointer included.

You should see: something that reads like a good briefing. If it does, the grounding will too. This is also the fastest way to catch a stale reference or a note that no longer applies — fix it now, in the artifact, not later in a session.

Step 4 — Attach where sessions launch

Switch to the Terminals view. Context attaches at two levels:

• Workspace-level — the artifact becomes the default context for every agent pane in that terminal workspace. The right move for a fleet or a standing effort: attach the briefing once, every session there inherits it.
• Pane-level — context for one specialist session, layered on top of the workspace default. A session's effective context is the union of both, deduplicated.

Attach your artifact at the workspace level for this walk.

You should see: back in the Context Artifacts view, the artifact now shows an "attached in" marker for that terminal workspace, with a jump straight to it.

Step 5 — Spawn a grounded session

In the workspace you attached to, add an agent pane (or launch the workspace fresh with agent panes — the setup dialog also sets model, reasoning effort, permission mode, and working folder per session).

You should see: a full, interactive Claude Code session start in a visible pane. It is a grounded session because the artifact was injected at launch — and only the context was injected: the session keeps all of its own tools, model settings, and permissions. Grounding changes what it knows at start, not what it can do.

Step 6 — Verify the grounding

Type into the pane and ask the session to play its briefing back:

Before we start: summarize what you understand this effort to be,
what has already been decided, and which files you plan to consult.

You should see: an answer that mirrors your artifact — the goal, the decisions, and your file references, named without any searching or directory exploration first. If the session instead starts exploring to orient itself, the grounding is thin: go back to step 1 and sharpen the notes or the references. The preview from step 3 is exactly what the session received, so the two should agree.

Step 7 — Iterate the artifact

The artifact is the living home of the effort's framing. As decisions land, update it — in the view, in any editor, or let an agent maintain it. Two properties to internalize while iterating:

• Grounding is captured at launch. Editing an artifact does not reach into sessions already running — a live agent's briefing never shifts mid-task. Respawn the pane (or start a fresh session) to carry the updated context.
• One mechanism, every door. Sessions you launch, sessions Voice stands up, and sessions agents spawn for other agents all resolve artifacts through the same backend — an agent-dispatched worker inherits the workspace's context exactly as your own sessions do. The artifact you just wrote is now the effort's briefing for everyone.

This is also the recommended preparation for a mission fleet: attach the effort's artifact to the fleet's workspace and every worker starts briefed — see Run a mission.

Where everything landed

Where to go deeper

• Context artifacts & grounding — why grounding is the operator's highest-leverage move
• Context Artifacts — the view in reference form
• Terminals — workspaces, agent panes, and spawn controls
• The knowledge graph — the three depths and when each is worth it