RomanNum3ral
/
cai
mirror of https://github.com/aliasrobotics/cai.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
cai/docs/tui/troubleshooting.md

3.5 KiB
Raw Blame History

Troubleshooting

⚡ CAI-Pro Exclusive Feature
The Terminal User Interface (TUI) is available exclusively in CAI-Pro. To access this feature and unlock advanced multi-agent workflows, visit Alias Robotics for more information.

Common issues and solutions when using CAI TUI.

API Configuration

API Key Not Working

Symptom: Authentication errors or "invalid API key" messages

Solutions:

  • Verify key in .env: CAI_API_KEY=your_key
  • Check key format and validity
  • Restart TUI after changes

Model Not Available

Symptom: Selected model returns errors

Solutions:

  • Verify API key has access to model
  • Check model name spelling
  • Review available models in dropdown

Agent Issues

Agent Not Responding

Symptom: Prompts hang or no response from agent

Solutions:

  • Check API rate limits
  • Verify network connection
  • Try different model
  • Check cost limits not exceeded

Wrong Agent Behavior

Symptom: Agent doesn't follow expected workflow

Solutions:

  • Verify correct agent selected
  • Use /compact to reduce context
  • Use /flush to clean conversation history
  • Check agent description matches your needs

Terminal Management

Can't Create New Terminal

Symptom: New terminal button doesn't work

Solutions:

  • Check maximum terminals reached (depends on layout)
  • Restart TUI

Terminal Not Responding

Symptom: Input doesn't work in specific terminal

Solutions:

  • Click terminal to focus
  • Check if prompt is running

Performance Issues

Slow Response Times

Symptom: Agent takes too long to respond

Solutions:

  • Try faster model (e.g., gpt-4o-mini)
  • Reduce context with /compact
  • Clear conversation history with /flush
  • Check network latency

High Memory Usage

Symptom: TUI consumes excessive RAM

Solutions:

  • Clear conversation history: /clear
  • Reduce number of active terminals
  • Restart TUI periodically

Session & Data Issues

Session Won't Load

Symptom: /load command fails

Solutions:

  • Verify file path is correct (paths like ~/file.jsonl are expanded automatically)
  • Use .jsonl from /save or compatible session logs — not /save .md exports (those are read-only reports)
  • Ensure file permissions and that the file exists

Stats Not Updating

Symptom: Stats tab shows stale or no data

Solutions:

  • Switch to different tab and back
  • Check API responses are completing
  • Restart TUI

Cost & Billing

Unexpected High Costs

Symptom: Token usage higher than expected

Solutions:

  • Check Stats tab for breakdown
  • Review context length
  • Set cost limits in .env
  • Use cheaper models for reconnaissance

Keyboard Shortcuts

Shortcuts Not Working

Symptom: Key combinations don't trigger actions

Solutions:

  • Check terminal intercepts keys
  • Verify TUI has focus
  • Use alternative shortcuts (see Keyboard Shortcuts)

Getting Help

If your issue isn't covered here:

  1. Check logs: ~/.cai/logs/latest.log
  2. Review documentation: Other guides in docs/tui/
  3. Report issues: Contact support with error logs

Related Documentation