Right context, right now. No lake required.
A Go CLI that auto-extracts signals from your git working context (branch name, commit messages, staged files), fetches related Jira tickets, GitHub PRs, and git history in parallel, and injects the assembled context into your AI coding agent before you start typing. No server. No database. No workflow change.
$ git checkout -b feat/PROJ-1234-oauth2-migration
$ claude # Claude Code's SessionStart hook fires
# → puddle fetch --format claude-hook
# → context injected silently before turn 1
The agent already knows: PROJ-1234's acceptance criteria, the linked PR's review comments, the reviewer who flagged the PKCE concern last week, the recent commits on the branch. You did not paste any of that.
Mid-conversation, when the agent sees a ref it doesn't recognize ("what about PROJ-512?", "did #847 ever land?"), it can pull more context on its own via the bundled skill — no need for you to leave the chat:
> what's the status on PROJ-512?
⏵ context-puddle skill: puddle fetch --signal ticket:PROJ-512
PROJ-512 is in review; acceptance criteria pivoted last Tuesday to require…
go install github.com/contextpuddle/puddle/cmd/puddle@latestPre-built binaries and a Homebrew tap are coming with the v0.1.0 release.
# 1. one-time per machine
puddle auth add github --device # OAuth device flow (no token paste)
puddle auth add jira # opens token-creation page in browser
# 2. one-time per AI agent
puddle install claude-code # SessionStart hook + on-demand skill
puddle install pi # gitignores .pi/APPEND_SYSTEM.md
puddle install cursor # gitignores rules + writes /puddle-fetch slash command
# 3. per-project
cd my-repo
puddle init # scaffolds .puddle.toml + gitignores .puddle.lock
puddle preview # see what would be injectedFor Pi and Cursor, run puddle fetch -t pi (or -t cursor) before launching
the agent. For Claude Code the hook fires automatically.
Session-start (proactive) — context lands before you type. Wired up via
each agent's session-start mechanism (Claude Code hook, Pi APPEND_SYSTEM.md,
Cursor rules file).
On-demand (reactive) — the agent calls puddle fetch --signal type:value
when it spots a ref it doesn't have context for. Installed as a Claude Code
skill or a Cursor /puddle-fetch slash command. Useful for refs that come up
mid-conversation, not in the branch name.
puddle fetch --signal ticket:PROJ-123
puddle fetch --signal pr:456
puddle fetch --signal repo:some-org/auth-service
puddle fetch --signal ticket:PROJ-1 --signal pr:42 # parallel| Target | Session-start delivery | On-demand | Token budget |
|---|---|---|---|
| Claude Code | SessionStart hook → puddle fetch --format claude-hook |
skill (auto-loaded) | 2,500 |
| Pi | .pi/APPEND_SYSTEM.md written by puddle fetch -t pi |
(v0.2 extension) | 4,000 |
| Cursor | .cursor/rules/puddle.mdc written by puddle fetch -t cursor |
/puddle-fetch |
3,000 |
| stdout | puddle fetch | pbcopy — pipe anywhere |
— | unlimited |
Layered TOML, project overrides user. See examples/ for full templates.
# .puddle.toml — at repo root
[sources.git]
enabled = true
commit_lookback = 10
[sources.github]
enabled = true
# auto-derived from origin URL when omitted
# default_owner = "your-org"
# default_repo = "your-repo"
[sources.jira]
enabled = true
[targets.claude_code]
token_budget = 2500Pin extra signals per task with .puddle.lock (gitignored by default):
ticket = "PROJ-4821"
related_repos = ["org/identity-service"]
prs = [892, 901]puddle install <agent> # claude-code | pi | cursor
puddle install claude-code --local # write to <repo>/.claude/ instead of ~/.claude/
puddle install claude-code --no-skill # hook only
puddle install claude-code --no-hook # skill only
puddle auth add <source> # github | jira
puddle auth list / remove
puddle fetch [-t <target>] [--format ...] [--no-cache] [--include-git]
puddle fetch --signal type:value [--signal …] # on-demand mode for skills/agents
puddle preview [-t <target>] [--show-output]
puddle init # scaffold .puddle.toml
puddle clear [--force] # remove generated files + cache
working context (branch, commits, files, .puddle.lock)
↓ regex extraction
typed signals (ticket_id, pr_number, repo_ref, file_path, ...)
↓ parallel fan-out (5s timeout per source)
fetchers (git, github, jira)
↓
ContextItems (deduplicated by source+kind+id, multi-source matches boost relevance)
↓ rank + truncate (per-item) + greedy fill (total budget)
formatter (claude-hook JSON | XML | Markdown | Cursor MDC)
↓
agent
Missing credentials produce a warning, not an error. A failing fetcher produces a warning, not an error. Puddle is useful from day one with no tokens at all (git fetcher works locally).
- macOS (Apple Silicon and Intel) — primary target
- Linux (amd64, arm64)
- Windows — best-effort at v0.1 (keychain behavior and path handling differ; full support tracked for v0.3)
Want to add a new source (Slack, Confluence, Linear, etc.)? See
docs/adding-an-adapter.md for a step-by-step
guide covering the Fetcher interface, config wiring, auth, and tests.
v0.1 (this release): regex extraction, three fetchers, three agents,
session-start hooks + on-demand agent skills, local config, file-backed
cache. See puddle-FUTURE.md (in-tree, not distributed) for what comes
next: LLM-enhanced Mode 2, Linear / Slack / Confluence fetchers, MCP
server mode, native Pi extension, organization-managed control plane.
See CONTRIBUTING.md. Bug reports and feature requests use the GitHub issue templates.
MIT — see LICENSE.