SpecStory Documentation

The Antigravity CLI (agy) stores all session and configuration data in ~/.gemini/antigravity-cli/. Understanding this layout is critical for locating logs, configuration, and conversation data.

Key directories and files:

• ~/.gemini/oauth_creds.json: Shared OAuth credentials used for authentication.
• ~/.gemini/config/projects/<projectId>.json: Maps a projectId (UUID) to a workspace path.
• ~/.gemini/antigravity-cli/settings.json: Contains {enableTelemetry, model, trustedWorkspaces[]}.
• ~/.gemini/antigravity-cli/conversations/<conversationId>.db: The canonical SQLite database used to resume sessions.
• ~/.gemini/antigravity-cli/brain/<conversationId>/: The primary directory for conversation data, containing logs and system messages.
• ~/.gemini/antigravity-cli/brain/<conversationId>/.system_generated/logs/transcript_full.jsonl: The primary source for parsing clean, native-JSON tool arguments.

~/.gemini/                                          # shared with Gemini CLI
├── oauth_creds.json                                # OAuth creds
├── config/
│   └── projects/<projectId>.json                   # projectId(UUID) -> workspace path map
└── antigravity-cli/                                # all Antigravity data lives here
    ├── history.jsonl                               # interactive-TUI prompt log
    ├── installation_id                             # UUID string
    ├── settings.json                               # {enableTelemetry, model, trustedWorkspaces[]}
    ├── keybindings.json
    ├── last_check.timestamp                        
    ├── cache/onboarding.json
    ├── bin/{agentapi,webm_encoder}                 
    ├── updater/update.lock
    ├── knowledge/knowledge.lock
    ├── cli.log -> log/cli-YYYYMMDD_HHMMSS.log       
    ├── log/cli-YYYYMMDD_HHMMSS.log                 
    ├── conversations/<conversationId>.db           # SQLite conversation store
    ├── conversation_summaries.db                   # SQLite index of conversations
    ├── scratch/                                    # default workspace
    └── brain/<conversationId>/                      # one dir per conversation
        └── .system_generated/
            ├── logs/
            │   ├── transcript_full.jsonl           # PRIMARY SOURCE
            │   └── transcript.jsonl                
            ├── messages/                            
            │   ├── <messageId>.json                
            │   ├── read.json                       
            │   └── cursor.json                     
            └── tasks/                               
                └── task-<N>.log                    

AIttributor is a lightweight git hook designed to detect active AI agents and append attribution metadata to git commit messages. It acts as a "license plate camera at commit time," providing a low-friction way to mark commits that were assisted by AI.

Core Mechanism:

1. It operates as a prepare-commit-msg git hook.
2. It detects active agents using four signals: agent-specific environment variables, process ancestry, sibling process tree matching the repository's current working directory, and agent breadcrumb files in known paths.
3. If an agent is detected, it appends specific git trailers to the commit message.

Key Limitations:

• It only provides commit-level attribution. It does not capture prompts, tool calls, line-level provenance, or micro-versioning.
• Correlation is coarse; it correlates by repository working directory and active agent presence at the time of commit. It may be inaccurate if multiple agents are active simultaneously.

Lore is designed to be idempotent, meaning re-running the engine on an unchanged repository will result in no changes. The engine uses a fingerprint based on size + mtime + PARSER_VERSION to skip redundant processing.

Key behaviors include:

• Accumulation: New sessions are appended to the corpus.
• Updates: If a session file grows or changes, it is updated rather than duplicated.
• Upgrades: A PARSER_VERSION bump triggers an automatic one-time full re-parse.
• Force Re-indexing: Use the --force flag to re-index everything regardless of fingerprints.
• Pruning: Running prune removes orphaned rows if a transcript is deleted or moved, and flags duplicate-identity groups if a project gains a new git_id (remote).
• Forging: The forged registry is authoritative. Running /lore after forging allows forged check to compare skill evidence against the current corpus and recommend actions like up-to-date, update, update-carefully (for hand-edited files), or orphaned.

When running specstory run, the CLI implements a debouncing mechanism to optimize cloud synchronization and prevent excessive API requests. This mechanism is designed to handle rapid sequences of events by coalescing updates and limiting the sync rate.

Debounce Rules

• Immediate Sync: A sync occurs immediately if no sync is currently in progress and more than 10 seconds have passed since the last sync for that specific session.
• Queue and Coalesce: If an event occurs within the 10-second debounce window, it is queued. If multiple events occur while an event is queued, only the latest event is kept (coalescing).
• Auto-flush: If an event is queued, the system will automatically trigger a sync once the 10-second debounce timer expires.
• Forced Flush: All pending syncs are flushed immediately when the specstory run process exits to prevent data loss.
• Per-session Isolation: Debouncing is applied per session; different sessions sync independently of one another.

The workthreads engine processes .specstory/history transcripts using specific clustering rules and lifecycle logic to prevent fragmentation (too many small threads) and mega-threads (one giant thread for the whole codebase).

Clustering Rules

1. Session as Unit: A single session's beats are unioned into one thread. A multi-prompt session is treated as one thread.
2. Rare Key Requirement: To merge two sessions, they must share at least two RARE keys. A key is a file or a distinctive symbol (snake_case, camelCase, or ALL_CAPS_WITH_UNDERSCORE). Ubiquitous keys (found in >4 sessions), config files (.env, package.json), and short abbreviations (AI, API, EOF) are ignored.
3. Bounded Union: A thread is capped at a maximum of 5 sessions. Any merge that would exceed this cap is refused.

Lifecycle Statuses

Threads are classified based on activity relative to the current date:

• closed: Latest outcome was a success, the thread has been quiet for $\ge 3$ days, and the last activity was $\le 30$ days ago. (Note: Threads are flagged as reverted if a beat ran a rollback command like git revert or git reset --hard).
• new: First activity occurred within the last 7 days.
• open: Activity occurred within the last 14 days.