Augment Code (Auggie CLI) session tracing

Send Auggie CLI session starts, stops, and ends to Future AGI using Augment’s hooks and the shared hook-to-OTLP emitter. Each conversation appears as an Auggie session trace with Agent stop child spans.

Prerequisites

• Auggie CLI 0.36.0 on macOS, Node.js 20 or later, and an Augment account signed in with auggie login.
• Python 3.9 or later on the PATH Auggie uses. The emitter needs no Python packages.
• Your Future AGI API and secret keys.

This recipe covers new CLI sessions only. Tool tracing, resumed conversations (--continue or --resume), Augment IDE extensions, Linux, and Windows are outside its scope. It does not export model calls, token usage, cost, prompts, or responses.

1. Install Auggie and the hook

Use the version covered by this recipe:

npm install --global @augmentcode/auggie@0.36.0
auggie login

Clone the maintained examples and run the installer for your repository:

git clone --depth 1 https://github.com/future-agi/docs.git fi-docs
fi-docs/examples/coding-agents/augment-code/install.sh --project /path/to/your/repo

The installer places the emitter and wrapper in ~/.augment/fi-hook-to-otlp/ and writes <repo>/.augment/settings.local.json. If that settings file already exists, it leaves it unchanged and prints the entries to merge into its hooks object. These workspace settings apply only to the CLI.

The generated configuration uses your home directory in place of /Users/you:

{
  "hooks": {
    "SessionStart": [{ "hooks": [{ "type": "command", "command": "/Users/you/.augment/fi-hook-to-otlp/futureagi-hook.sh", "timeout": 5000 }] }],
    "Stop":         [{ "hooks": [{ "type": "command", "command": "/Users/you/.augment/fi-hook-to-otlp/futureagi-hook.sh", "timeout": 5000 }] }],
    "SessionEnd":   [{ "hooks": [{ "type": "command", "command": "/Users/you/.augment/fi-hook-to-otlp/futureagi-hook.sh", "timeout": 5000 }] }]
  }
}

The wrapper prints nothing and exits successfully even if Python or the emitter is unavailable. It does not inject context or prevent the agent from stopping. Timeouts are in milliseconds; the emitter exports in a background process.

Keep the workspace settings out of version control: they contain your absolute home path. The installer adds a local Git exclusion unless the file is already ignored; it does not edit .gitignore. If Git already tracks the file, remove it from tracking before adding personal settings. Home paths containing a single quote are not supported by the installer.

To trace new sessions across all repositories instead, run the installer without --project. That writes ~/.augment/settings.json, which Augment IDE extensions also read. For CLI-only, repository-scoped tracing, use the project installation above and remove any Future AGI entries from the user-level file. If you used an earlier configuration, also remove its Future AGI PostToolUse entry; retain unrelated hooks.

2. Add your Future AGI keys

Create the emitter’s credential file with owner-only permissions. If you already use it for another coding agent, update the existing file instead of replacing it.

mkdir -p ~/.config/fi-hook-to-otlp
(umask 077; cat > ~/.config/fi-hook-to-otlp/env <<'EOF'
FI_API_KEY=your-futureagi-api-key
FI_SECRET_KEY=your-futureagi-secret-key
FI_PROJECT_NAME=auggie-sessions
FI_HOOK_CAPTURE_CONTENT=0
EOF
)
chmod 600 ~/.config/fi-hook-to-otlp/env

Auggie’s environment variables take precedence over this file. For self-hosted Future AGI, also set FI_BASE_URL; the emitter sends traces to $FI_BASE_URL/tracer/v1/traces. See the shared configuration reference for other settings.

3. Run a new session

From the repository where you installed the hooks, start a new conversation:

auggie --print "Explain what a README is in one sentence. Do not use tools."

Open Observe in Future AGI and select auggie-sessions. Open the Auggie session trace to see its Agent stop child and stop cause. Each subsequent Stop event in the same interactive conversation adds another child; it is not a model-request span.

What is captured

Hook	Result in Future AGI
SessionStart	Starts an Auggie session, keyed by conversation_id and exposed as session.id. The root is exported with the first stop span.
Stop	Adds an Agent stop child with augment.stop.cause, and updates augment.stop.last_cause on the root. Only the cause error marks the child ERROR, with the fixed message agent stopped with error.
SessionEnd	Ends the session span. A session with no stop event exports nothing.

There are no turn spans or tool spans in this configuration. Stop events mark when the agent stops responding, not the duration of a model call.

Privacy

The session configuration exports conversation identifiers, lifecycle timing, stop causes, and status. It does not export prompts, responses, user email, model display names, or workspace paths. The adapter ignores context, conversation, user_prompt, _exchange, and workspace_roots, including when those fields appear in a hook payload.

Leave includeUserContext and includeConversationData off: enabling them adds sensitive data to the local hook input without adding session telemetry. Keep FI_HOOK_CAPTURE_CONTENT=0; session events do not need content capture. See the shared privacy reference.

Troubleshooting

No trace appears.

1. Confirm Auggie is signed in, the settings file contains the three hook entries, and a response has ended. An empty session sends no trace.
2. Check that ~/.augment/fi-hook-to-otlp/futureagi-hook.sh is executable and that python3 resolves in the shell used to launch Auggie.
3. Set FI_HOOK_LOG_FILE=/tmp/fi-hook.log in the credential file and start another session. http=401 or http=403 indicates an authentication problem; error= indicates an export failure. If no line appears after a stop, check hook registration, credentials, and that FI_HOOK_DISABLED is not 1.

Other repositories still produce traces. Remove the Future AGI entries from ~/.augment/settings.json and retain only the project-scoped entries.

Uninstall

Remove the three Future AGI hook entries from the workspace or user settings before deleting ~/.augment/fi-hook-to-otlp/. To pause all integrations using the shared emitter configuration, set FI_HOOK_DISABLED=1 in its credential file instead.