Skip to content

docs: agent variable #7365

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dianed-square merged 2 commits into from
Feb 19, 2026
+26 −2
Merged

docs: agent variable #7365

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
caf6181
agent variable
dianed-square Feb 19, 2026
0026328
use cases
dianed-square Feb 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 26 additions & 2 deletions documentation/docs/guides/environment-variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -611,14 +611,27 @@ These variables are automatically set by goose during command execution.
| Variable | Purpose | Values | Default |
|----------|---------|---------|---------|
| `GOOSE_TERMINAL` | Indicates that a command is being executed by goose, enables [customizing shell behavior](#customizing-shell-behavior) | "1" when set | Unset |
| `AGENT` | Generic agent identifier for cross-tool compatibility, enables tools and scripts to detect when they're being run by goose | "goose" when set | Unset |
| `AGENT_SESSION_ID` | The current session ID for [session-isolated workflows](#using-session-ids-in-workflows), automatically available to STDIO extensions and the Developer extension shell commands | Session ID string (e.g., `20260217_5`) | Unset (only set in extension/shell contexts) |

### Customizing Shell Behavior

Sometimes you want goose to use different commands or have different shell behavior than your normal terminal usage. For example, you might want goose to use a different tool, prevent goose from running `git commit`, or block long-running development servers that could hang the AI agent. This is most useful when using goose CLI, where shell commands are executed directly in your terminal environment.
Sometimes you want goose to use different commands or have different shell behavior than your normal terminal usage. Common use cases include:
- Skipping expensive shell initialization (e.g. syntax highlighting, custom prompts)
- Blocking interactive commands that would hang the agent (e.g., `git commit`)
- Redirecting to agent-friendly tools (e.g., `rg` instead of `find`)
- Building cross-agent tools and scripts that detect AI agent execution
- Integrating with MCP servers and LLM gateways

This is most useful when using goose CLI, where shell commands are executed directly in your terminal environment.

**How it works:**
1. When goose runs commands, `GOOSE_TERMINAL` is automatically set to "1"

goose provides the `GOOSE_TERMINAL` and `AGENT` variables you can use to detect whether goose is the executing agent.

1. When goose runs commands:
- `GOOSE_TERMINAL` is automatically set to "1"
- `AGENT` is automatically set to "goose"
2. Your shell configuration can detect this and change behavior while keeping your normal terminal usage unchanged

**Examples:**
Expand All @@ -645,6 +658,17 @@ if [[ -n "$GOOSE_TERMINAL" ]]; then
fi
```

```bash
# Detect AI agent execution using standard naming convention
if [[ -n "$AGENT" ]]; then
echo "Running under AI agent: $AGENT"
# Apply agent-specific behavior if needed
if [[ "$AGENT" == "goose" ]]; then
echo "Detected goose - applying goose-specific settings"
fi
fi
```

### Using Session IDs in Workflows

STDIO extensions (local extensions that communicate via standard input/output) and the Developer extension's shell commands automatically receive the `AGENT_SESSION_ID` environment variable. This enables you to create session-isolated workflows and make it easier to:
Expand Down
Loading