Threading Needles' development workflow for Claude Code, open sourced and packaged as a Claude Code plugin marketplace.
Awl is the workflow we use daily at Threading Needles for AI-assisted development. It's battle-tested on real projects and optimized for efficient, context-aware AI collaboration.
Awl integrates with your development tools through MCP servers and CLI tools:
- Linear - Issue tracking, sprint planning, ticket lifecycle (MCP bundled with
awl-dev, automatic OAuth)awl-dev: Core research agents and workflow commandsawl-pm: Advanced PM workflows (cycle analysis, milestone tracking, backlog grooming)
- GitHub - Pull requests, code review, repository management (CLI via
gh)awl-dev: PR creation, branch management, worktree workflows
- PostHog - Error tracking, session replay, stack traces, HogQL queries (MCP)
awl-debugging: PostHog error tracking MCP integration
- PostHog - User behavior, conversion funnels, feature analytics (MCP)
awl-analytics: PostHog MCP integration (~40k tokens when enabled)
- Context7 - Library documentation lookup (MCP, ~2k tokens)
awl-dev: Built-in, always available
- DeepWiki - GitHub repository documentation (MCP, ~1.5k tokens)
awl-dev: Built-in, always available
- Exa - Web research and external documentation (API)
awl-dev: External research agent
Why CLI + lightweight MCP? Most development sessions don't need heavy integrations:
- Start with
awl-dev(~3.5k tokens): Core workflow + Linear + GitHub - Enable
awl-analyticswhen analyzing user behavior (~+40k tokens) - Enable
awl-debuggingwhen investigating production errors (~+20k tokens) - Disable when done to free context for code and conversation
This keeps your typical session lean while having powerful tools available when needed.
Awl is a 5-plugin system for Claude Code focused on token efficiency, session-aware MCP management, and persistent context through parallel agent research, structured handoffs, and shared memory systems.
awl-dev (Core - Always enabled)
- 9 research agents (codebase, history, Linear, external)
- 17 commands covering full dev lifecycle
- Linear MCP bundled (OAuth, no API tokens needed)
- Handoff system for context persistence
- ~3.5k context (lightweight MCPs: DeepWiki, Context7)
awl-pm (Optional - Enable for project management)
- Linear-focused project management workflows
- 7 commands: analyze-cycle, analyze-milestone, analyze-initiative, update-status, report-daily, groom-backlog, sync-prs
- Research-first architecture (Haiku for data, Sonnet for analysis)
- 6 specialized agents: linear-research, cycle-analyzer, milestone-analyzer, initiative-analyzer, backlog-analyzer, github-linear-analyzer
- Cycle management, milestone tracking, initiative portfolio analysis
- Actionable insights and recommendations (not just data dumps)
awl-analytics (Optional - Enable when needed)
- PostHog MCP integration (~40k context)
- Product analytics and user behavior analysis
- Conversion funnels and cohort analysis
- 3 specialized analytics commands
awl-debugging (Optional - Enable when needed)
- PostHog error tracking, session replay, and HogQL
- Production error monitoring and debugging
- Stack trace analysis and session replay context
- 3 specialized debugging commands
awl-meta (Optional - For advanced users)
- Discover workflows from community repos
- Import and adapt patterns
- Create new workflows
# In Claude Code:
/plugin marketplace add Threading-Needles/awl
/plugin install awl-devThat's it. No setup script, no config file, no API tokens — Linear authenticates via OAuth on first use.
Try it:
/awl-dev:research-codebase TICKET-123Every workflow command takes a Linear ticket ID as a positional argument. Commands are stateless — no hidden "current ticket" state between runs.
See QUICKSTART.md for details.
Alternatively, install plugins manually via Claude Code plugin system:
# Add the marketplace repository
/plugin marketplace add Threading-Needles/awl
# Install core workflow (required)
/plugin install awl-dev
# Optional: Install PM plugin (Linear project management)
/plugin install awl-pm
# Optional: Install analytics plugin (if you use PostHog)
/plugin install awl-analytics
# Optional: Install debugging plugin (PostHog error tracking)
/plugin install awl-debugging
# Optional: Install meta plugin (workflow discovery)
/plugin install awl-metaPlugins automatically load/unload MCPs when enabled/disabled:
# Enable PM tools for sprint planning and cycle reviews
/plugin enable awl-pm # Lightweight CLI-based, minimal context
# Enable analytics when analyzing user behavior
/plugin enable awl-analytics # Loads PostHog MCP (+40k context)
# Disable when done to free context
/plugin disable awl-analytics # Unloads PostHog MCP (-40k context)
# Enable debugging for incident response
/plugin enable awl-debugging # Loads PostHog error tracking MCP
# Can enable multiple plugins simultaneously
/plugin enable awl-pm awl-analytics awl-debuggingWhy this matters: Most development sessions don't need analytics or debugging MCPs. Starting
with just awl-dev keeps your context at ~3.5k tokens instead of ~65k, leaving more room for
code and conversation.
Keep your Awl plugins up to date with bug fixes and new features:
# Update the marketplace to fetch latest from GitHub
claude plugin marketplace update awl
# Restart Claude Code to load updated plugins
# (Exit and reopen, or start a new session)When to update:
- 🐛 Bug fixes: Patch versions (e.g., 3.0.0 → 3.0.1) - Fix issues like incorrect CLI syntax
- ✨ New features: Minor versions (e.g., 3.0.0 → 3.1.0) - New commands or capabilities
- 🔄 Breaking changes: Major versions (e.g., 3.0.0 → 4.0.0) - May require configuration updates
Important: A restart is required for plugin updates to take effect. Active sessions use the old version until you restart Claude Code.
Check your versions:
# List installed plugins and their versions
/plugin listNeed help?
- Installation & Configuration Guide - Complete setup, installation, and configuration
- Claude Code Plugin Guide - Official plugin documentation
/awl-dev:research-codebase → /awl-dev:create-plan → /awl-dev:implement-plan → /awl-dev:validate-plan → /awl-dev:create-pr → /awl-dev:merge-pr
With handoffs for context persistence:
/awl-dev:create-handoff → /awl-dev:resume-handoff
Agents proactively monitor context during implementation and will prompt you to create handoffs before running out of context, creating structured handoff documents that add to persistent memory.
Learn More:
- Agentic Workflow Guide - Complete guide showing research, planning, handoff, worktree, implementation, verify, and PR workflows
- Context Engineering - Token efficiency strategies and context management patterns
- PR Lifecycle skill - PR creation, review, and merge workflow (auto-loaded on feature branches)
- Parallel Agent Research - Multiple specialized agents research concurrently
- Context Compression - Research compressed into structured summaries
- Focused Planning - Planning agents work with compressed context
- Persistent Memory - Handoffs preserve context across sessions
Uses the official Linear MCP server for rich Linear integration with structured tool calls.
Context Persistence
- Structured handoff documents for context preservation
- Research artifacts saved and referenceable
- Plan documents that persist implementation context
Token Efficiency
- Parallel agents compress research before synthesis
- Focused agents for specific tasks
- Context-aware handoff prompts
Stateless Commands
- No config files, no hidden state between runs
- Ticket ID and team key passed explicitly as arguments
- Linear MCP authenticates via OAuth on first use
Core Tools:
- Claude Code
- Git
CLI Integrations:
gh- GitHub CLI (required for PR creation, merge, sync)
MCP Tools (bundled with plugins):
- Linear - Built into
awl-dev - Context7 & DeepWiki - Built into
awl-dev(~3.5k tokens) - PostHog - Built into
awl-analyticsandawl-debugging
Run the doctor:
/awl-dev:doctorWe welcome contributions! Open issues for bugs, workflow suggestions, or to share how you've adapted Awl to your needs.
- Full Documentation - Comprehensive guides
- Quick Start - Installation and first steps
- Usage Guide - How to use all features
- Architecture - How it's built
MIT - Use it however you want!
Built by Threading Needles