wip-cli 0.1.4

Developer situational awareness for the agentic coding era.

wip — Developer situational awareness for the agentic coding era

AI agents ship code while you sleep. They merge PRs, create branches, and push commits across your repos — and you need to know what happened. wip scans your git repositories, passively detects agent activity (Claude, Copilot, Cursor, Devin), and gives you a complete picture: what changed, what's dirty, what's stashed, and what needs your attention. With AI-powered briefings, it turns raw git signals into narrative summaries so you can pick up exactly where you — and your agents — left off.

Demo

Features

• 🕵️ Agent detection — passively detect coding agent activity (Claude, Copilot, Cursor, Devin) from git signals, with active/recent/stale status tracking
• 🤖 AI-powered briefings — narrative summaries, standup drafts, natural language queries — all agent-aware
• 🧭 Context-aware git help — ask how to untangle branches, recover stashes, or fix mistakes — the AI sees your actual repo state
• 🔌 Multi-provider LLM — Anthropic, OpenAI, and Gemini all implemented
• 🔍 Auto-discover git repos in configured directories
• 📊 Status overview — dirty files, stashes, ahead/behind tracking
• 🌿 Recent branches — see branches you've touched recently
• 💬 Recent commits — your commits from the last 24 hours
• 📂 Enriched file-level context — changed files with diff stats, stash descriptions, commit bodies and file lists
• 📝 Work-in-progress tracker — jot down tasks, link them to repos, see them in your briefing
• 🎨 Rich terminal output — color-coded status with icons
• 📦 Multiple output modes — human-friendly or JSON for scripting

Installation

From PyPI (recommended)

pip install wip-cli

Or with pipx for an isolated install:

pipx install wip-cli

From source

git clone [e-mail]:drmnaik/wip.git
cd wip
pip install -e .

Requirements: Python 3.9+ PyPI: https://pypi.org/project/wip-cli/

Quick Start

1. Set up wip (interactive)

wip config init

This walks you through:

• Directories — which folders to scan for git repos
• Author name — your git identity (auto-detected from git config)
• LLM provider — optional, enables AI-powered briefings (Anthropic, OpenAI, or Gemini)

2. Run your first briefing

wip                # Show briefing
wip --verbose      # Full details
wip --json         # JSON output for scripting

3. Set up an LLM provider (optional)

AI features (wip ai briefing, wip ai standup, wip ai ask) require an LLM provider. You can configure this during wip config init, or manually — pick one below.

Anthropic (Claude)

1. Get an API key at console.anthropic.com
2. Export it: export ANTHROPIC_API_KEY="sk-ant-..."
3. Add to your config:

[llm]
provider = "anthropic"
model = "claude-haiku-4-5-20251001"
api_key_env = "ANTHROPIC_API_KEY"

OpenAI (GPT)

1. Get an API key at platform.openai.com
2. Export it: export OPENAI_API_KEY="sk-..."
3. Add to your config:

[llm]
provider = "openai"
model = "gpt-4o"
api_key_env = "OPENAI_API_KEY"

Google Gemini

1. Get an API key at aistudio.google.com
2. Export it: export GEMINI_API_KEY="..."
3. Add to your config:

[llm]
provider = "gemini"
model = "gemini-2.0-flash"
api_key_env = "GEMINI_API_KEY"

Tip: Add the export line to your ~/.bashrc or ~/.zshrc so the key persists across sessions. Leave model empty to use the provider's default.

Configuration Reference

Config is stored at ~/.wip/config.toml. You can edit it directly or re-run wip config init. View current settings with wip config show.

directories = ["/Users/you/projects", "/Users/you/work"]
author = "Your Name"
scan_depth = 3
recent_days = 14

[llm]
provider = "anthropic"
model = "claude-haiku-4-5-20251001"
api_key_env = "ANTHROPIC_API_KEY"

# Optional: customize agent detection patterns
[agents]
authors = ["claude", "copilot", "cursor", "devin", "codex", "github-actions", "bot"]
branch_patterns = ["agent/", "claude/", "copilot/", "devin/", "cursor/"]

Field	Description	Default
directories	Folders to scan for git repos	current directory
author	Your git author name (filters commits)	auto-detected
scan_depth	How deep to recurse into directories	3
recent_days	Lookback window for recent branches	14
[llm] provider	anthropic, openai, or gemini	—
[llm] model	Model ID (empty = provider default)	—
[llm] api_key_env	Env var name holding your API key	—
[agents] authors	Substrings matched against commit author names	Claude, Copilot, Cursor, Devin, etc.
[agents] branch_patterns	Branch prefixes indicating agent activity	agent/, claude/, copilot/, etc.

Commands

Core

wip               # Show briefing (default command)
wip status        # Alias for wip
wip --json        # Output as JSON
wip --verbose     # Show full details
wip config init   # Interactive setup
wip config show   # Display current config
wip version       # Show version

Work-in-progress tracker

wip add "fix auth bug"                     # Add item (auto-links to current repo)
wip add "read docs" --repo /path/to/repo   # Add item linked to specific repo
wip done 1                                 # Mark item #1 as done
wip list                                   # Show open items
wip list --all                             # Show all items including completed

AI-powered commands

Requires an LLM provider configured in ~/.wip/config.toml and the corresponding API key set as an environment variable.

wip ai briefing                 # Narrative briefing
wip ai standup                  # Generate a standup update from git activity
wip ai ask "what was I working on yesterday?"
wip ai ask "anything I forgot to push?"
wip ai ask "summarize my week"

# Context-aware git help — the AI sees your actual branches, dirty files, and stashes
wip ai ask "I have diverged branches, how do I cleanly get back to main?"
wip ai ask "how do I recover what I stashed last week?"
wip ai ask "what git commands do I need to untangle this mess?"

Example Output

Standard briefing (wip)

 wip — 3 repos scanned

 work-in-progress — 2 items

  #1  fix auth token refresh (auth-service) — 2h ago
  #3  update API docs (api-gateway) — 1d ago

auth-service (fix/token-refresh) ⚠
  3 dirty · 1 stash · last commit 14h ago
  2 ahead, 0 behind origin
  agents:
    claude on agent/add-tests — 12 commits, 14 files (23m ago) ● active
    copilot on copilot/logout — 4 commits, 3 files (7h ago) ○ stale
  wip:
    #1 fix auth token refresh (2h ago)
  recent: main (3d), feat/oauth (5d)
  commits today:
    a1b2c3 fix retry logic for token refresh (2h ago)

frontend (main) ✓
  clean · 2 stashes
  0 ahead, 0 behind origin

api-gateway (main) ↓
  clean · 3 behind origin
  wip:
    #3 update API docs (1d ago)

AI briefing (wip ai briefing)

## Briefing

### auth-service
Claude was busy overnight — 12 commits on agent/add-tests, touching
14 files. It added unit tests for the token refresh flow and the retry
logic you were working on. The branch is still active (last commit 23m ago).
Meanwhile, you have 3 dirty files on fix/token-refresh with a stash that
looks like an alternative approach. Review Claude's test coverage before
resuming your fix — there may be overlap.

### frontend
Clean, nothing to do here. You left a TODO about form validation on
Tuesday but no urgency.

### api-gateway
3 commits behind origin — just needs a pull. Your note says to update
the API docs once auth-service lands.

Suggested focus: review Claude's agent/add-tests branch in auth-service,
then resume your token refresh fix.

Status Icons

• ✓ — Clean repo, up to date
• ⚠ — Dirty files (modified, staged, or untracked)
• ↓ — Behind remote (needs pull)

Privacy

• wip status runs entirely locally — no data leaves your machine.
• wip ai commands send repository metadata (commit messages, branch names, file paths, work items) to your configured LLM provider (Anthropic, OpenAI, or Gemini). No file contents or diffs are sent.
• API keys are never stored in config — only the environment variable name is saved.

Development

# Install dependencies
pip install -e .

# Run from source
python -m wip.cli

Roadmap

Phase 1: Foundation + Scanner ✅

• Config management, repo discovery, git status scanning, terminal output

Phase 2: Interactive Worklist ✅

• wip add/done/list commands with repo linking and persistent state

Phase 3: LLM Integration ✅

• Provider abstraction (Anthropic, OpenAI, and Gemini all implemented)
• wip ai briefing, wip ai standup, wip ai ask with streaming
• Prompt assembly from status data, config-driven provider/model selection

Phase 4: Passive Agent Detection ✅

• Detect coding agent activity from git signals (author names, branch patterns)
• Agent sessions surface in wip, wip --json, and all AI commands automatically
• Configurable author/branch patterns with sensible defaults (zero config required)
• Status tracking: active (<1h), recent (<24h), stale (>24h)

Phase 5: Enriched File-Level Context ✅

• Changed files with diff stats (insertions/deletions), color-coded by stage in verbose output
• Stash descriptions surfaced in verbose display and LLM prompts
• Commit bodies (capped at 3 lines) and per-commit file lists (capped at 10 paths) in LLM context

Ideas and contributions welcome — see docs/CONTEXT.md for architecture details.

Contact

• LinkedIn: Mahesh Naik
• Issues: GitHub Issues

License

MIT

Author

Built by Mahesh Naik with Claude