Skip to content
term2

Troubleshooting & FAQ

File & Directory Locations

Section titled “File & Directory Locations”

term2 stores logs, sessions, settings, and caches in platform-standard directories:

Configuration (settings.json)

Section titled “Configuration (settings.json)”
  • Linux: ~/.local/state/term2-nodejs/settings.json (or $XDG_STATE_HOME/term2-nodejs/settings.json)
  • macOS: ~/Library/Logs/term2-nodejs/settings.json
  • Windows: %LOCALAPPDATA%\term2-nodejs\Log\settings.json

OAuth tokens are stored separately under envPaths('term2').config (Linux example: ~/.config/term2-nodejs/; macOS Preferences). TERM2_CONFIG_DIR overrides it; this is not the settings state/log directory.

Application Logs

Section titled “Application Logs”
  • Linux: ~/.local/state/term2-nodejs/logs/ (or $XDG_STATE_HOME/term2-nodejs/logs/)
  • macOS: ~/Library/Logs/term2-nodejs/logs/
  • Windows: %LOCALAPPDATA%\term2-nodejs\Log\logs\

Conversation History

Section titled “Conversation History”
  • Linux: ~/.local/share/term2-nodejs/conversations/ (or $XDG_DATA_HOME/term2-nodejs/conversations/)
  • macOS: ~/Library/Application Support/term2-nodejs/conversations/
  • Windows: %LOCALAPPDATA%\term2-nodejs\Data\conversations\

Model Catalog Cache

Section titled “Model Catalog Cache”
  • Linux: ~/.cache/term2-nodejs/models/ (or $XDG_CACHE_HOME/term2-nodejs/models/)
  • macOS: ~/Library/Caches/term2-nodejs/models/
  • Windows: %LOCALAPPDATA%\term2-nodejs\Cache\models\

Common Issues & Solutions

Section titled “Common Issues & Solutions”

1. Stale Model Cache

Section titled “1. Stale Model Cache”

Symptom: Newly released models do not appear in /model or --list-models, or deprecated model names still show up.

Fix:

  • In the CLI, run with --refresh:
    Terminal window
    term2 --list-models --refresh
  • In the interactive model picker (Ctrl+O), press Ctrl+R to force a cache refresh directly from provider APIs.
  • Alternatively, remove cached model files from your platform’s cache directory:
    Terminal window
    # Linux
    rm -rf ~/.cache/term2-nodejs/models/*

2. Missing Provider Credentials

Section titled “2. Missing Provider Credentials”

Symptom: missing-credentials, missing-grok-login, or missing-codex-login errors.

Fix:

  • For Grok: run term2 --grok-login.
  • For Codex / ChatGPT: run term2 --codex-login.
  • For API key providers: check that OPENAI_API_KEY, OPENROUTER_API_KEY, or ANTHROPIC_API_KEY is exported in your current shell environment, or configure it via /settings.

3. Home Directory Start Warning

Section titled “3. Home Directory Start Warning”

Symptom: term2 displays a warning when started directly in ~ (your home directory).

Explanation: Starting term2 in your root home directory exposes your entire user tree (downloads, desktop, documents, hidden configs) to file searches and commands.

Fix: Navigate to a specific project directory (cd ~/projects/my-app && term2) before launching. For text-only questions without filesystem or shell tools, use term2 --lite.

4. Non-Interactive Tool Execution Fails

Section titled “4. Non-Interactive Tool Execution Fails”

Symptom: Running term2 "do something that writes a file" outputs text but makes no modifications.

Explanation: A positional prompt without --auto-approve selects builtin:lite (except persisted Mentor/Orchestrator), so tools are unavailable. --auto-approve opts out of implicit Lite and enables GREEN/YELLOW heuristic policy, not /auto-approve always; RED shell remains refused, and the process may still exit 0. Inspect stderr or JSON approval_rejected.

Fix: Pass --auto-approve:

Terminal window
term2 --auto-approve "Fix the typo in README.md"

5. Web Gateway Port or Socket Conflicts

Section titled “5. Web Gateway Port or Socket Conflicts”

Symptom: term2 serve reports that the socket or port is already in use.

Fix:

  • Check if an existing gateway instance is running:
    Terminal window
    ps aux | grep "term2 serve"
  • Kill the process holding the --listen port or socket path. The server removes a stale Unix socket itself and refuses to unlink a path that is not a socket; inspect or move a conflicting non-socket path instead.

6. Context Limit Pauses After Upgrading

Section titled “6. Context Limit Pauses After Upgrading”

Requests are checked against the model catalog’s context window before sending, reserving output space and an estimation margin. agent.maxRequestInputTokens can lower the input ceiling, not raise the model’s capacity.

New installations enable local context compaction in auto mode, but upgrades retain saved settings. If your settings contain agent.contextCompaction.enabled: false, enable it to opt in. Earlier releases saved agent.maxOutputTokens: 32000; that remains an explicit allocation. Lower it for small-window models, or remove the key from settings.json to use the adaptive cap (at most a quarter of a known context window and 32,000 tokens).

Non-interactive context pauses exit with code 2 and a resume hint. Review the limit before resuming; do not blindly repeat a command that may already have changed files.