01. GETTING STARTED GUIDE

Briefed bridges the AI latency context gap for developers by automatically summarizing code diffs and keeping context logs up-to-date in target files like CLAUDE.md. This ensures your AI pair programmer (Cursor, Windsurf, Claude Dev) is always synced with recent pulled, merged, or rebased edits in the background.

📦 1. Installation

Install Briefed globally once — then run briefed init inside any repo you want to track. You only install once, set up per-repo.

# Install globally (do this once)
npm install -g briefed-cli

⚙️ 2. Hooks Initialization

Navigate to the root directory of any Git repository you want to track, then run:

# Navigate into your project repo first
cd /path/to/your-repo

# Install hooks into this repo
briefed init

# Or use the interactive setup wizard (sets backend, target file)
briefed init --interactive

This installs post-merge and post-rewrite hooks into .git/hooks/. If you use Husky, it appends into .husky/ instead. Repeat this step for every repo you want Briefed to track. The global install means you only install the CLI once.

✅ What happens after init

Every time you run git pull, git merge, or git rebase, the hook fires silently in the background. It diffs what changed, summarizes it (via your configured LLM or the built-in mechanical fallback), and appends a structured entry to your context file. Your AI coding tool reads that file automatically — no manual context dumping needed.

🔑 3. Setting API Keys

To connect Cloud LLM backend aggregators (Google Gemini or Anthropic Claude), you must configure credentials. You have three flexible options depending on your security preferences:

Option A: Shell Environment Variables (Temporary/Session-Only)

Exporting the API key inside your terminal session keeps it in-memory, making it extremely secure against accidental check-ins to GitHub.

# Git Bash / macOS / Linux
export GEMINI_API_KEY="your-google-studio-api-key"

# Windows PowerShell
$env:GEMINI_API_KEY="your-google-studio-api-key"

# Windows CMD Prompt
set GEMINI_API_KEY=your-google-studio-api-key

Option B: Global User Configuration (Permanent for all local projects)

Place a .briefed.json configuration file inside your global user home directory (e.g. C:\Users\Username on Windows or ~/.briefed.json on macOS/Linux):

{
  "apiKey": "your-gemini-or-anthropic-api-key"
}

Briefed automatically deep-merges this global file as a fallback, ensuring your credentials are accessible across all repositories without cluttering repository folders.

Option C: Local Configuration (Permanent for this repo)

Place `.briefed.json` directly in your repository root directory. Make sure you add .briefed.json to your .gitignore file to prevent leaking secrets on Git repositories.

🚀 4. Triggering Your First Sync

To manually trigger a diff and write your first context entry, run:

briefed run

Use --verbose to inspect exactly what it's doing — which files changed, which backend was used, and how long it took:

briefed run --verbose

💡 CI/CD is optional

Briefed works locally via Git hooks — that's the primary mechanism. GitHub Actions is only useful if your team merges PRs through the GitHub web UI and wants the context file committed back to the repo centrally. For most developers using Briefed locally, CI setup is not needed. See the CI/CD Integration guide if you need it.

🤖 Custom Rules for Agentic IDEs (Cursor, Windsurf, Claude Code)

💡 Why This Prompt is Vital

By default, when your AI assistant (like Claude Code in terminal or Cursor in editor) boots up, it has no native awareness that Briefed is running git hooks and maintaining a live chronological history in your workspace context files.

Feeding this System Instruction Directive into your agent's custom rules (e.g. .cursorrules, Claude's custom prompt, or your global IDE rules) instructs the agent to automatically parse the Briefed block. This prevents the agent from running expensive, redundant git diff commands (saving tokens and API latency) and guarantees instant, cross-agent memory alignment!

Copy and paste the exact rules directive block below into your global custom instructions, .cursorrules, or Claude Code system prompts:

# Git Context Alignment (Briefed CLI)
This project utilizes the Briefed CLI tool, which automatically updates the active AI context file (e.g. CLAUDE.md) after every \`git pull\`, merge, or rebase.

## Instructions for the AI Agent:
1. Always parse the dated Git context blocks written inside the \`\` and \`\` markers in your context file to keep your short-term memory aligned with the latest workspace state.
2. Do not attempt to run manual git diffs or git logs to understand recent pull histories; instead, inspect the structured logs inside the context markers.
3. The context log is bounded dynamically under a strict \`maxTotalWords\` ceiling (~1000 words) to protect your context window. Parse only the active entries between the start and end markers.
4. Entries have been sanitized client-side of any internal reasoning (\`<think>\`) blocks and lockfile bloat, leaving only high-signal category blocks (\`FILES\`, \`ADDED\`, \`REMOVED\`, \`RENAMED\`, \`DEPS\`).
5. Use this structural information to instantly grasp which endpoints, APIs, or components were recently introduced or deprecated, ensuring all code suggestions align 100% with the latest codebase updates.