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: 
/context create <context-name> <path_1> [path_2...] [options]
Options:
FlagDescription
--mode <mode> or -mDefines how files will be processed. Modes: full, summary, chunked, smart, or knowledge (documentation corpora as a keyless RAG knowledge base).
--description <text> or -dAdds a text description to help identify the context.
--tags <tag1,tag2> or -tAdds tags for easier filtering and organization.
--force or -fOverwrites an existing context with the same name.
Example: 
# Creates an 'api-core' context with smart mode, description, and tags
/context create api-core ./src/services ./docs/api \
  --mode smart \
  --description "Context with the API core and documentation" \
  --tags golang,api

​
attach and detach: Attach and Detach from Session

These commands control which contexts are active in your current conversation.
CommandDescription
/context attach <context-name>Attaches a context to the session.
/context detach <context-name>Removes a context from the session.
/context attachedLists all currently attached contexts.

​
Advanced Chunk Attachment

If a context was created with --mode=chunked, you can attach specific parts of it:
FlagDescription
--chunk <N>Attaches only chunk number N.
--chunks <N,M,...>Attaches a list of specific chunks.
--priority <num>Defines the order in which attached contexts are sent (lower number = higher priority).
--rag [K] (or --retrieve, -r)Semantic retrieval: injects only the top-K passages relevant to the turn, instead of the raw content. K optional (default 8).
Example: 
# Attaches only chunks 1 and 3 from the 'legado-db' context with high priority
/context attach legado-db --chunks 1,3 --priority 10

​
--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 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.
# Attach 'api-core' in retrieval mode — only relevant passages per turn
/context attach api-core --rag
# Or control K (number of passages):
/context attach api-core --rag 12
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.
CommandDescription
/context listLists all available contexts with basic metadata.
/context show <name>Displays detailed information about a context, including the complete list of files.
/context inspect <name>Provides a deep statistical analysis of the context, such as file type distribution, line counts, and chunk size analysis. Use --chunk N to inspect a specific chunk.

​
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.