FAQ / Troubleshooting

Common questions and solutions.

Install / Build

Q: Build fails with "cgo: C compiler not found"

A: Install a C compiler. On macOS: xcode-select --install. On Linux: apt install build-essential or equivalent.

Q: Build fails with sqlite3 errors

A: Hash uses mattn/go-sqlite3 which requires cgo. Ensure CGO_ENABLED=1.

Q: How do I update?

A: Pull latest and rebuild:

git pull && go build -o hash ./cmd/hash

Agent connection

Q: "command not found: claude-agent-acp"

A: Install the ACP adapter, or change command to your agent's path:

npm install -g @agentclientprotocol/claude-agent-acp

Q: My config says claude-code-acp and stopped getting updates

A: The adapter package was renamed from @zed-industries/claude-code-acp to @agentclientprotocol/claude-agent-acp, and the executable from claude-code-acp to claude-agent-acp. Install the new package and update command in config.toml.

Q: Agent times out

A: Increase timeout in config:

config.toml
[agent]
timeout = "300s"

Q: HTTP agent returns empty responses

A: Check the model name matches what your server expects.

Q: How do I debug agent issues?

A: Check the agent command is installed and on your PATH first (e.g., which claude-agent-acp). Hash prints the same checklist when a connection fails.

Q: How do I leave an agent conversation?

A: Press Esc or Ctrl+C, submit an empty line, or type /exit. Saying something like "done" or "that's all" also ends it.

Context

Q: Why isn't my env var in context?

A: Env vars are opt-in. Press Ctrl+P and select it.

Q: Why is context so large?

A: Check if you're including large LastOutput. Use | head -50 before piping.

Q: Can I exclude secrets automatically?

A: Env vars are opt-in — simply don't select sensitive ones in the context picker (Ctrl+P).

TUI / Rendering

Q: Icons don't show correctly

A: Install a Nerd Font and configure your terminal to use it. Or disable:

config.toml
[completions]
file_icons = false

Q: Colors look wrong

A: Hash uses 256-color mode. Ensure TERM is set correctly (e.g., xterm-256color).

Q: Multiline input breaks display

A: Try [input] gutter = false or check terminal size.

Performance

Q: ?? is slow

A: This is agent latency, not Hash. Try a local model or check network.

Q: Completion is slow

A: Tool-native completions (Cobra) can be slow for some commands. Disable with:

config.toml
[completions]
cobra_enabled = false

Q: Startup is slow

A: Check init_commands and startup files. Agent connects lazily (not at startup).

Privacy

Q: What gets sent to the agent?

A: Only what you select in Ctrl+P:

  • Working directory path
  • Git branch name (not file contents)
  • Kubectl context name
  • Selected env var names and values
  • Recent command strings
  • Piped output (if you pipe)

Q: Are my commands logged anywhere?

A: Only locally in ~/.local/share/hash/history.db. Nothing leaves your machine unless you send it via ??.

Q: Can I use Hash without any agent?

A: Yes. Without ??, Hash is a normal shell with editor-style input and learning. No network calls.

Q: Does learning data leave my machine?

A: No. All patterns are stored locally in SQLite.