Terminal Context

When you send a query to your AI tool, Lacy prepends relevant terminal context — current directory, git branch, recent commands, last exit code, and terminal output. Only what changed since the last query is included.

What gets sent

text

[cwd: /path/to/project] [git: main] [exit: 1] [recent: npm test]
[terminal-output]
npm ERR! Test failed. See above for more details.
[/terminal-output]
why did that fail?

Each context field is only included when it has changed since the last query:

Field	Included when
`cwd`	Directory changed since last query
`git`	Branch changed since last query (detached HEAD shows short hash)
`exit`	Non-zero exit AND a shell command ran since the last query
`recent`	Shell commands run since last query (ring buffer, max 10)
`terminal-output`	Last terminal output (tmux/screen/iTerm2/Terminal.app), when available

Terminal output capture

Lacy lazily captures terminal output at query time using your terminal's API. Supported integrations:

tmux — tmux capture-pane (checked first inside multiplexers)
screen — screen -X hardcopy
iTerm2 — AppleScript get content
Terminal.app — AppleScript get contents

Output is stripped of ANSI escape codes and capped at 50 lines (configurable). If no terminal API is available, terminal output is omitted.

Note

tmux and screen are checked first. Terminal emulator APIs (iTerm2, Terminal.app) return the wrong content when running inside a multiplexer.

Delta tracking

Context is delta-based to avoid redundant noise. Each agent query resets the counters, so the next query starts fresh. The /new session command also clears all context state.

Recent commands use an explicit ring buffer, not shell history — this prevents agent queries themselves from leaking into the context.

Configuration

yaml

# ~/.lacy/config.yaml
context:
  output_lines: 50   # max terminal output lines (default: 50)

Starting a fresh session

bash

/new     # clears all context state; next query sends full context