Configuration

How loghop stores local project state, global install choices, and runtime environment settings.

Configuration Locations

loghop uses three local state files:

Location	Scope	Contents
`<project>/.loghop/config.toml`	Project	Goal, counters, active topic, handoff settings
`~/.loghop/config.toml`	Global	Saved install choices, shim prefix, TUI preferences, tracked project roots
`~/.loghop/projects.toml`	Global registry	Registered projects and recent activity

All project files are private local state. loghop init adds .loghop/ and loghop.md to .gitignore.

Project Configuration

Generated by loghop init in .loghop/config.toml:

version = 1
project_name = "my-app"
goal = "Add user auth"
handoff_counter = 42
session_counter = 156
topic_counter = 8
active_topic_id = "T-003"
handoff_patch_lines = 160

Field	Description
`version`	Project config schema version
`project_name`	Display name for the project
`goal`	Default goal used by handoffs and new topics
`handoff_counter`	Last allocated handoff number
`session_counter`	Last allocated session number
`topic_counter`	Last allocated topic number
`active_topic_id`	Topic used by default for new runs
`handoff_patch_lines`	Maximum diff lines included in a handoff

Global Configuration

Created or updated by loghop install, loghop init, TUI preferences, and install repair commands:

# loghop global config

[install]
install_claude_hooks = true
install_codex_shim = true
install_prompt_block = true
installed_version = "0.1.0"
codex_shim_prefix = "/home/user/.local/bin"
project_roots = ["/home/user/projects/my-app"]

[tui]
theme = "harbor_dark"
language = "en"

The exact keys depend on which integrations you choose. Re-running loghop init or loghop install is idempotent.

Project Registry

The project registry lives at ~/.loghop/projects.toml:

[[project]]
name = "my-app"
path = "/home/user/projects/my-app"
registered = "2026-05-01T10:00:00Z"
last_used = "2026-05-17T14:30:00Z"
goal = "Add user auth"
last_session = "S-042"
session_count = 42
handoff_count = 12

Use loghop projects cleanup to remove registry entries whose paths no longer exist.

Environment Variables

Variable	Description
`LOGHOP_LOG_LEVEL`	Log level (`DEBUG`, `INFO`, `WARNING`, etc.; default `INFO`)
`LOGHOP_LOG_MAX_BYTES`	Maximum log file size before rotation
`LOGHOP_LOG_BACKUP_COUNT`	Number of rotated log files to keep
`LOGHOP_PROVIDER_AUTH_RETRIES`	Claude auth preflight retry count
`LOGHOP_PROVIDER_AUTH_RETRY_DELAY_MS`	Delay between auth preflight retries
`LOGHOP_DISABLE_CLAUDE_SHELL_ENV_PROBE`	Set to `1` to disable interactive shell env probing for Claude credentials
`LOGHOP_NO_COLOR` / `NO_COLOR`	Disable colored output
`LOGHOP_ASCII`	Use ASCII-safe glyphs in terminal output
`LOGHOP_LANG` / `LANGUAGE` / `LANG`	Language preference for localized TUI text
`LOGHOP_REAL_CODEX` / `LOGHOP_REAL_CLAUDE`	Internal wrapper escape hatch pointing to the real provider binary

Provider credentials such as ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, and ANTHROPIC_BASE_URL are read from the environment when launching Claude.

Custom Secrets Redaction

You can define custom regular expression patterns to redact proprietary identifiers, internal URLs, or specific tokens. Custom patterns can be configured in the global configuration (~/.loghop/config.toml) or the project configuration (.loghop/config.toml).

These custom patterns are processed before loghop’s built-in system secret rules.

TOML Schema

Add one or more [[redaction]] tables to your configuration file:

[[redaction]]
pattern = 'MY_SUPER_SECRET_\d+'
replacement = '[redacted custom secret]'

[[redaction]]
pattern = '(?i)\b(api-token|token-id)\s*=\s*\S+'
replacement = '\1=[redacted custom token]'

Field	Type	Description
`pattern`	String	A regular expression pattern to search for. Must be a valid Python regex pattern. Remember to escape special characters appropriately in TOML (e.g. use double backslashes `\\` in double-quoted strings, or single quotes for literal strings where no backslash escaping is needed).
`replacement`	String	The replacement text. Supports regex group backreferences (e.g., `\1`).

Ignoring Files

loghop respects .loghopignore in the project root:

# Patterns to exclude from handoffs
*.env
secrets/
credentials.json

Files matching .loghopignore are excluded from handoff packets. Session metadata and timeline events remain local under .loghop/.

Handoff Format

Handoffs are markdown files with YAML frontmatter:

---
id: H-042
ts: 2026-05-17T14:30:00Z
provider: claude
goal: Add user auth
status: built
topic_id: T-003
_signature: 0123456789abcdef
---
# Project Handoff

## Goal
Add user auth

## Project Summary
[Project overview]

## Repository
[Branch, head, dirty state]

## Handoff Context
[Included files, ignored files, patch truncation]

## Changed Files
- `src/auth.py`
- `src/models.py`

## Patch
```diff
[Uncommitted changes]
```

The _signature value is an HMAC over the frontmatter and markdown body. It detects local tampering but is not an encryption mechanism.

Storage Layout

.loghop/
├── config.toml                 # Project configuration
├── handoffs/
│   └── H-042.md                # Handoff documents
├── sessions/
│   ├── S-042.md                # Session metadata
│   └── S-042.transcript.jsonl  # Redacted transcript
├── topics/
│   └── T-003.md                # Work topic metadata
├── timeline.jsonl              # Cross-provider timeline
├── integrity.key               # Private HMAC key
└── loghop.log                  # JSON logs

loghop.md                       # Generated context (gitignored)

~/.loghop/
├── config.toml                 # Global install/TUI preferences
├── projects.toml               # Project registry
├── loghop-prompt.md            # Optional shared prompt block
└── loghop.log                  # Global logs

Resetting Configuration

To reset project configuration:

rm .loghop/config.toml
loghop init

To reset global configuration:

loghop uninstall -y --purge
loghop install