# Goose

Canonical: https://hypaware.ai/docs/integrations/goose

**Status:** Supported. **Setup id:** `goose`. **Backfill:** Yes.

HypAware reads [Goose](https://github.com/aaif-goose/goose)'s local session
database, `~/.local/share/goose/sessions/sessions.db`, read-only. It polls
the database every 60 seconds for new messages, and a scheduled import every
15 minutes brings in existing sessions. It does not route Goose's model
traffic or change Goose's settings.
The same database serves the Goose CLI and Desktop on Linux and macOS.

## What is recorded

Sessions and messages, including your prompts, Goose's responses, tool calls
and their output, the tokens Goose records for each response, and each
session's working directory. A session's title is generated by the model from
your conversation, so it is treated as message content.

Subagent sessions are recorded as their own sessions, linked to the session
that started them. Sessions Goose keeps hidden, such as `goose run
--no-session` and the checks `goose configure` runs, are never read.

## Set it up

`hyp setup` offers Goose when it finds the session database. On a new
installation you can pick it without the prompts:

```sh
hyp setup --source goose
hyp status
```

To add Goose to an existing installation, run `hyp setup` in a terminal,
choose **Reconfigure**, and select Goose; your current choices stay selected.
`hyp setup --source goose` refuses to change an existing configuration, and
`--force` replaces it rather than adding to it.

This integration installs no skills into Goose.

### Use a different database location

The daemon does not see a `GOOSE_PATH_ROOT` set in your shell, because it
runs under launchd or systemd with its own environment. A `hyp backfill goose`
run from that shell does see it, so the two can read different databases. If
you set `GOOSE_PATH_ROOT`, or keep the database somewhere else, add this entry
to the
existing `plugins` list in your HypAware configuration, preserving the other
entries:

```json
{
  "name": "@hypaware/goose",
  "config": {
    "sessions_db": "/absolute/path/to/sessions.db"
  }
}
```

See [configuration](https://hypaware.ai/docs/configuration/index.md#locate-and-validate-configuration)
for the config location, then apply and check the change:

```sh
hyp config validate
hyp daemon restart
hyp status
```

## Import existing history

Setup does not import your existing sessions itself. The scheduled import
picks them up within 15 minutes, or run it now:

```sh
hyp backfill goose --dry-run
hyp backfill goose
```

New messages arrive on the next poll, up to a minute after Goose writes them.
A scheduled import also runs every 15 minutes. It picks up changes Goose
makes to a session it already wrote, so those can take up to 15 minutes to
appear. Set `backfill.window_days` to limit both imports to recent sessions.
With `backfill.on_join` set to `false`, neither runs.

## Privacy

Directory markings and `.hypignore` apply to each session's working directory.
To stop recording one session, pass its Goose session id, such as
`20261103_4`. Goose prints the id when a session starts, and
`goose session list` shows it for each session:

```sh
hyp session ignore 20261103_4
```

Goose reads saved exclusions on its next poll, so an ignore takes effect
within a minute.

The command saves the exclusion through the HypAware gateway, so it works only
while HypAware also records another client through its gateway. On an install
that records only Goose, it prints one `hyp session` error line, exits `3`, and
saves nothing.
Ignore the session's working directory instead, which also stops recording
every other Goose session there:

```sh
hyp privacy ignore /path/to/session/working/dir
```

See [marking directories](https://hypaware.ai/docs/privacy/index.md#marking-directories).

**Goose writes its own copy of your prompts.** Goose saves the full body of
every model request, including your prompts, to `llm_request.*.jsonl` files in
its logs directory. HypAware does not read those files, and HypAware's privacy
controls do not cover them.

## Limits

- Sessions from Goose versions before 1.10.0, which kept each session in its
  own `.jsonl` file, are not imported.
- Goose Desktop sessions are recorded only when Desktop writes them to the
  same `sessions.db`. Paths only Desktop uses are not read.
- The older macOS location, `~/Library/Application Support/Block/goose/`, is
  not read. Point `sessions_db` at a database there if you still use one.
- If Goose changes its database schema, `hyp status` reports the missing
  column and HypAware records nothing until a release supports the new
  schema. It never writes partial rows.

For status messages and fixes, see
[troubleshooting](https://hypaware.ai/docs/troubleshooting/index.md#goose-records-nothing).