Longer tasks across sessions
A task larger than one session, for example a migration or a feature across many files, fills the context window of a session. Answers get slower, more expensive and less precise. The method below keeps each session small and the state of the work in the projectdocs, where the next session reads it.
The AI does each step with its own tools. Your part is to ask for them.
What the AI can do itself
| Step | Tools | Mode |
|---|---|---|
| Query the code | describe_symbol, call_chain, code_search, find_similar, find_ui_source | any |
| Re-analyse after changes | reanalyze_project, sweep_status, status | any |
| Write plans, summaries, handovers | projectdocs_create_entry, projectdocs_append_entry_section | Brave |
| Anchor text to code and commits | projectdocs_anchor_add, projectdocs_commit_anchor_add | Brave |
| Group the files of a step | changelists_create, changelists_set_active | Brave |
| Start the next session | session_new_chat_from_entry | Brave |
Short requests are enough: "Re-analyse before you continue." "Create a changelist for this step." "Anchor the summary to the symbols you changed."
Ask for anchors
The AI writes a summary of its work more readily than it anchors it. Ask for both:
- Code anchors: "Anchor the summary to the functions you changed." Later,
anyone working on such a function finds the summary from the code, in the
gutter or through
projectdocs_for_symbol. - Commit anchor: "Anchor the commit to the entry." A click on the anchor opens the commit in the Git view.
When the AI renames or moves an anchored symbol, it should move the anchors in
the same step (spec_reanchor for specs, projectdocs_anchor_remove and
projectdocs_anchor_add for projectdocs). Otherwise the anchors become suspect.
See Anchors.
Work through a plan in slices
Prerequisite: the session is in Brave mode.
- Plan. Ask the AI to write the whole task as a plan in the projectdocs: a phase with slices, each with a goal, the affected areas and a check that tells when it is done.
- One slice. Ask the AI to implement the next slice in its own changelist.
- Record. At the end of the slice, the AI
- appends a summary to the plan or writes a summary entry,
- anchors it to the central symbols,
- commits and anchors the commit,
- re-analyses the project.
- Hand over. The AI writes a handover section into the entry: what is done, the next slice, the state of the tree with the last commit, open checks, open questions.
- New session. Start a new session from the entry
(New Chat from this), or let the AI start it with
session_new_chat_from_entry. Continue with step 2.
Example request:
Work through phase 12 slice by slice. Create a changelist per slice. After each slice: summary into the plan, anchors on the changed symbols, commit with commit anchor, re-analyse. Then write a handover and start a new session from the plan with the handover as first message.
For a single question or a small fix, a normal session is enough. Ask for the anchors anyway.
Subagents
With Claude (CLI), the session can hand a self-contained part of the work to a subagent: research, a search across many files, a review. The subagent reads in its own context and returns a short result. The main session stays small.
Built-in agents:
| Agent | Task | Does not |
|---|---|---|
explorer | Find files and symbols, answer factual questions about the code | change anything |
researcher | Research libraries, APIs and practices, return a brief | decide for the project |
planner | Turn a goal into a step-by-step plan | implement the plan |
reviewer | Review a diff for correctness, style and tests | rewrite the code |
issue-solver | Reproduce a bug, find the cause, propose a fix | ship the fix |
summarizer | Write a session summary for the projectdocs | change code |
ui-designer | Produce an HTML/CSS wireframe with accessibility notes | build the production UI |
Subagents run on the Worker Model — Claude (subagents) from the Claude
tab of AI Settings, by default Haiku. The code changes stay with the main
session, where you see them. Own agents are Markdown files in
~/.codeexplorer/agents/ or .codeexplorer/agents/ of the exploration. See
Project context.
Limits
- The new session knows only what is written down. A decision that is only in the old conversation is lost at the switch.
session_new_chat_from_entryopens the session in the Tracemoor window that started the old one.