Skip to main content
While session management (/session) saves the conversation history, context management (/context) saves the content of your working environment. It is the most powerful feature for those working on multiple projects or who frequently need to consult the same codebase. A Context is a named “snapshot” of one or more files and directories, processed and saved to disk for reuse at any time.

​
The Lifecycle of a Context

Context usage follows a simple and powerful flow:
1

Create (/context create)

You define a set of files and folders, process them with a specific mode (e.g., smart, chunked), and save the result with a name.
2

Attach (/context attach)

You “attach” one or more saved contexts to your current conversation session.
3

Use

While attached, the context content is automatically sent to the AI with all your prompts, providing deep and continuous knowledge about your project.
4

Detach (/context detach)

When you no longer need the context, you detach it to free up space in the AI prompt.

​
Context Management Commands

Here are all the available subcommands for managing your contexts.

​
create: Create a New Context

Creates and saves a new context from files and directories. Syntax:
Options: Example:

​
attach and detach: Attach and Detach from Session

These commands control which contexts are active in your current conversation.

​
Advanced Chunk Attachment

If a context was created with --mode=chunked, you can attach specific parts of it: Example:

​
--rag: Semantic Retrieval (don’t dump raw data)

The problem: injecting whole files blows the context window on any non-trivial codebase. The --rag flag fixes it: instead of the raw dump, it embeds the context’s passages and, each turn, injects only the top-K most relevant to the current question. For documentation or code/infra corpora, prefer --mode knowledge: same principle, but with no API key required (keyless BM25), an index card in the prompt and the @knowledge tool for the agent to investigate.
How it works:
1

Segmentation

Files are split into line-aware, overlapping passages (~300 tokens each) — a fine grain, distinct from the token-budget chunk. IDs are content hashes, so unchanged files skip re-embedding.
2

Embed once, cache on disk

Passages are embedded lazily and persisted per context; edited/removed passages are pruned (never serve stale text).
3

Retrieve at prompt time

The turn’s query is embedded and the top-K passages by cosine (with a relevance floor) are injected.
Requires an embedding provider (CHATCLI_EMBED_PROVIDER — voyage, openai or bedrock). Set the provider after ChatCLI was already running? /reload rebuilds and rewires it on the spot. Without one, --rag falls back transparently to whole content, with a warning. It is opt-in: without --rag, the attachment behaves exactly as before (zero regression).
Cache-aware: the retrieved content is query-driven, so it is injected in the prompt’s volatile zone — never poisoning the cached prefix. And --rag cannot be combined with --chunk(s) (semantic vs. manual selection are contradictory).
In a synthetic measurement, the injected block dropped to 44% of the raw size while still retrieving the right passage from a synonym query — on large contexts the saving is far greater. It reuses the same vindex primitive as RAG + HyDE — provider-agnostic, OS-agnostic, no new env vars.

​
list, show, and inspect: View Contexts

These commands help you understand what is in your saved contexts.

​
Other Management Commands

Permanently deletes a context.
Combines multiple contexts into a new one, removing duplicate files.
Exports a context to a JSON file, making backup and sharing easier.
Imports a context from a JSON file.
Shows global statistics about all your contexts (total count, size, etc.).
Displays a help screen specific to context commands.

​
Next Steps

You now know the most powerful automation and context management features of ChatCLI. To wrap up, let’s document the features that ensure portability and tool integration in scripts.

Non-Interactive Mode

Use ChatCLI in scripts, automations, and CI/CD pipelines.

Session Management

Save and restore complete conversation histories.