CacheWraith is a terminal-first AI chat workspace built with Textual. You launch one command, stay inside one interface, and do everything important from the TUI: chat, stream responses, switch agents, inspect status, and review recent history.

• Terminal-first workflow with one main command: cachewraith-cli
• Streaming chat with Gemini and Claude
• In-app agent switching with Ctrl+S or /agent
• Persistent history for completed prompts and responses
• Setup/help state inside the TUI when no agent is installed
• Optional cw alias that opens the same app

GPT is intentionally hidden until it has a real implementation.

• Python 3.8+
• At least one supported AI CLI:
  • Gemini CLI: npm install -g @google/gemini-cli
  • Claude Code: npm install -g @anthropic-ai/claude-code

git clone https://github.com/yourusername/cachewraith.git
cd cachewraith
pip install -e .

If you already have a local checkout, the included installer installs the real repo into its own virtual environment:

./install.sh

cachewraith-cli

Optional alias:

cw

Version check:

cachewraith-cli --version

1. Run cachewraith-cli.
2. CacheWraith loads config and detects Gemini and Claude availability.
3. If an agent is available, it opens directly into chat and auto-selects:
   • default_agent if available
   • otherwise Gemini
   • otherwise Claude
   • otherwise the first available agent
4. If no agents are available, CacheWraith stays inside the TUI and shows setup help instead of exiting.

Switching agents resets the active chat context intentionally, so each agent session starts clean.

• /help
• /agent
• /switch
• /status
• /history
• /clear
• /exit

• Ctrl+S switches agents
• Ctrl+C quits CacheWraith

Completed prompt/response pairs are written to CacheWraith history storage. Each entry records:

• agent/provider name
• prompt
• response
• success or failure
• execution time

Sensitive content matching history.ignore_patterns is redacted before it is written.

Config lives at ~/.config/cachewraith/config.yaml.

Example:

default_agent: gemini

agents:
  gemini:
    enabled: true
    model: gemini-2.5-pro
  claude:
    enabled: true
    model: claude-3-opus

history:
  max_entries: 1000
  ignore_patterns:
    - password
    - secret
    - token

python -m venv venv
source venv/bin/activate
pip install -e ".[dev]"
pytest