CacheWraith

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.

What It Supports

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

Requirements

• 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

Install

From Source

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

Local Installer

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

./install.sh

Run

cachewraith-cli

Optional alias:

cw

Version check:

cachewraith-cli --version

Terminal UI Flow

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.

Slash Commands

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

Keyboard Shortcuts

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

History

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.

Configuration

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

Development

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