Skip to content

contexts.md

Latest commit

 

History

History
334 lines (241 loc) · 10.1 KB

contexts.md

File metadata and controls

334 lines (241 loc) · 10.1 KB

Context Management

Contexts are separate conversations. Each context maintains its own:

  • Message history
  • Summary (from compaction)
  • Tasks (stored in VFS at /home/<name>/tasks/)
  • System prompt (optional override)
  • Configuration (optional override via local.toml)

Goals are flock-scoped — shared across all contexts in a flock, not per-context. See Flock Management below.

Switching Contexts

# Switch to a context (creates if it doesn't exist)
chibi -c rust-learning

# Continue in that context
chibi "Tell me about ownership"

# Switch to another context
chibi -c web-project

# Switch back to previous context
chibi -c -

The current context is persisted in ~/.chibi/session.json, along with the previous_context for quick switching.

Auto-Named Contexts

# Create a new context with timestamp name (e.g., 20240115_143022)
chibi -c new

# Create with a prefix (e.g., bugfix_20240115_143022)
chibi -c new:bugfix

Previous Context Reference

Use - as a shortcut to reference the previous context. When using -c -, it works just like cd - in bash - the current and previous contexts swap places, allowing you to toggle back and forth:

chibi -c dev          # Switch to 'dev', previous='default'
chibi -c production   # Switch to 'production', previous='dev'
chibi -c -            # Switch to 'dev', previous='production' (swapped!)
chibi -c -            # Switch to 'production', previous='dev' (swapped back!)

Swap Behavior: The swap behavior means you can quickly toggle between two contexts:

chibi -c work         # Working on work project
chibi -c personal     # Switch to personal project (work is now previous)
chibi -c -            # Back to work (personal is now previous)
chibi -c -            # Back to personal (work is now previous)
# Keep toggling as needed!

Using with Other Commands: The - reference works with any command that accepts a context name:

chibi -c staging      # Switch to staging
chibi -D -            # Delete the previous context (production)
chibi -G - 20         # Show last 20 log entries from previous context
chibi -C - "query"    # Ephemerally run a query in previous context (no swap)

How it works:

  • session.json tracks implied_context and previous_context fields
  • When using -c -, implied and previous contexts swap (like cd -)
  • Ephemeral switches (-C -) use previous but don't swap or persist changes
  • Other commands (-D -, -G -, etc.) just resolve to the previous context name
  • - is a reserved name and cannot be used as an actual context name
  • Error if no previous context exists (e.g., on first invocation)

Ephemeral Contexts

Use -C to run in a context without changing your current context:

# Current context: default
chibi -C research "Find info about quantum computing"
# Still in: default (research was used only for that command)

This is useful for:

  • Running one-off tasks in other contexts
  • Spawning sub-agents
  • Scripts that shouldn't affect user's current context

Listing Contexts

# List all contexts
chibi -L

# Output shows lock status:
# * default [active]    # Currently in use by a chibi process
#   coding [stale]      # Lock exists but process likely crashed
#   research            # No lock, not in use
# Show current context info (name, message count, tasks, goals)
chibi -l

Context Operations

Rename

# Rename current context
chibi -r new-name

# Rename a specific context
chibi -R old-name new-name

Delete

# Delete current context (switches to default first)
chibi -d

# Delete a specific context
chibi -D old-project

Archive (Clear History)

Archiving saves messages to transcript and clears the active context:

# Archive current context
chibi -a

# Archive a specific context
chibi -A old-context

Compact

Compacting summarizes messages and starts fresh:

# Compact current context (uses LLM to summarize)
chibi -z

# Compact a specific context (simple archive, no LLM summary)
chibi -Z other-context

Context Locking

When chibi is actively using a context, it creates a lock file to prevent concurrent access.

How It Works

  1. When chibi starts, it tries to acquire a lock on the context
  2. A background thread updates the lock timestamp periodically (every lock_heartbeat_seconds)
  3. Other chibi processes will fail if they try to use a locked context

Lock Status

The -L flag shows lock status:

  • [active] - Lock was updated recently (within 1.5x heartbeat interval)
  • [stale] - Lock exists but is old (process likely crashed)
  • No indicator - No lock, context is free

Stale Lock Handling

If a process crashes, its lock becomes stale. Chibi automatically cleans up stale locks and acquires a new one.

Activity Tracking & Auto-Destroy

Chibi tracks when each context was last used. This enables automatic cleanup of test contexts.

Activity Tracking

Every time chibi runs with a context, it updates the last_activity_at timestamp in state.json (context metadata). This happens automatically during normal usage.

Auto-Destroy

Contexts can be marked for automatic destruction using lifecycle flags:

# Auto-destroy after 60 seconds of inactivity
chibi --destroy-after-inactive 60 -c test-context

# Auto-destroy at a specific Unix timestamp
chibi --destroy-at 1737820800 -c ephemeral-context

How it works:

  • Auto-destroy checks run at the start of every chibi invocation
  • A context is destroyed if:
    • --destroy-at <TS> was set and current time > TS, OR
    • --destroy-after-inactive <SECS> was set and current time > last_activity_at + SECS
  • Values are stored in state.json; not set by default

Use cases: Ephemeral agent contexts, test cleanup, short-lived task contexts.

Per-Context System Prompts

Each context can have its own system prompt:

# View current context's system prompt
chibi -n system_prompt

# Set from text
chibi -y "You are a helpful coding assistant"

# Set from file
chibi -y ~/prompts/coder.md

# Set for a specific context
chibi -Y research "You are a research assistant"

Custom prompts are stored in ~/.chibi/contexts/<name>/system_prompt.md. If not set, the default from ~/.chibi/prompts/chibi.md is used.

Example: Different Personalities

chibi -c coding
chibi -y "You are a senior software engineer. Be precise and technical."

chibi -c creative
chibi -y "You are a creative writing assistant. Be imaginative and playful."

chibi -c default  # Uses the default chibi.md prompt

Per-Context Configuration

Each context can override global settings. See configuration.md for details.

# The config file location
~/.chibi/contexts/<name>/local.toml

Inspecting Contexts

# Inspect current context
chibi -n system_prompt   # View system prompt
chibi -n reflection      # View reflection (global)
chibi -n tasks           # View tasks
chibi -n home            # View chibi home directory
chibi -n list            # List what can be inspected

# Inspect a specific context
chibi -N research tasks
chibi -N coding system_prompt

Viewing History

# Show last N entries from current context
chibi -g 10

# Show last N entries from a specific context
chibi -G research 20

# Negative numbers show from the beginning
chibi -g -5  # First 5 entries

Storage Structure

~/.chibi/
├── state.json                   # Context registry (names, created_at, auto-destroy settings)
├── session.json                 # CLI session state (implied_context, previous_context)
├── vfs/
│   ├── home/<name>/
│   │   └── tasks/              # Structured tasks (.task files)
│   ├── site/                    # Site-wide flock data
│   │   ├── goals.md
│   │   └── prompt.md
│   ├── flocks/registry.json     # Centralised flock membership (SYSTEM only)
│   └── flocks/<name>/           # Named flock data
│       ├── goals.md
│       └── prompt.md
└── contexts/<name>/
    ├── transcript/              # Authoritative conversation log (partitioned)
    │   ├── manifest.json        # Partition metadata
    │   ├── active.jsonl         # Current write partition
    │   └── partitions/          # Archived read-only partitions
    ├── context.jsonl            # LLM context window (derived from transcript)
    ├── context_meta.json        # Internal cache metadata (system prompt mtime, last combined prompt)
    ├── local.toml               # Per-context config overrides (optional)
    ├── summary.md               # Conversation summary (from compaction)
    ├── inbox.jsonl              # Messages from other contexts
    ├── system_prompt.md         # Custom system prompt (optional)
    ├── .lock                    # Lock file (when active)
    └── .dirty                   # Marker for context rebuild (temporary)

Tool cache is stored in the VFS at /sys/tool_cache/<context>/ (not in the context directory on disk).

Flock Management

Flocks are named groups of contexts that share goals and prompts. Every context implicitly belongs to the site flock (site:<site_id>). Contexts can join additional named flocks.

# Join a flock (creates it if it doesn't exist)
chibi --flock-join myteam

# Leave a flock
chibi --flock-leave myteam

# List flocks for current context
chibi --flock-list

# Set goals for a flock (from the CLI)
chibi --flock-goals myteam "Focus on shipping feature X"

# Set goals for the site flock
chibi --flock-goals site "Maintain quality and test coverage"

Within a conversation, contexts can manage their own flock membership using the flock_join and flock_leave tools, and update goals using the update_goals tool.

Goals from all flocks a context belongs to are injected into the system prompt as attributed sections (--- GOALS [flock-name] ---). Prompts from /site/prompt.md and /flocks/<name>/prompt.md are similarly injected.

See transcript-format.md for details on the JSONL file formats.