awl-pm

Awl - Claude Code Workspace

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.

Tech Stack & Integrations

Awl integrates with your development tools through MCP servers and CLI tools:

Project Management & Issue Tracking

• Linear - Issue tracking, sprint planning, ticket lifecycle (MCP bundled with awl-dev, automatic OAuth)
  • awl-dev: Core research agents and workflow commands
  • awl-pm: Advanced PM workflows (cycle analysis, milestone tracking, backlog grooming)

Version Control & Code Hosting

• GitHub - Pull requests, code review, repository management (CLI via gh)
  • awl-dev: PR creation, branch management, worktree workflows

Error Monitoring & Debugging

• PostHog - Error tracking, session replay, stack traces, HogQL queries (MCP)
  • awl-debugging: PostHog error tracking MCP integration

Product Analytics

• PostHog - User behavior, conversion funnels, feature analytics (MCP)
  • awl-analytics: PostHog MCP integration (~40k tokens when enabled)

Documentation & Code Search

• 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

Token Efficiency Strategy

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-analytics when analyzing user behavior (~+40k tokens)
• Enable awl-debugging when 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.

What's Inside

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)

• 11 research agents (codebase + infrastructure)
• 18 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
• 5 commands: analyze-cycle, analyze-milestone, report-daily, groom-backlog, sync-prs
• Research-first architecture (Haiku for data, Sonnet for analysis)
• 5 specialized agents: linear-research, cycle-analyzer, milestone-analyzer, backlog-analyzer, github-linear-analyzer
• Cycle management and milestone tracking with target date feasibility
• 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

Quick Setup (5 Minutes)

Get started in 5 minutes with the unified setup script:

# Download the setup script
curl -O https://raw.githubusercontent.com/Threading-Needles/awl/main/setup-awl.sh
chmod +x setup-awl.sh

# Run it (requires interactive input)
./setup-awl.sh

This script will guide you through:

• Prerequisites check and installation (jq, etc.)
• Project configuration (ticket prefix, project name)
• Integration setup (Linear, PostHog, Exa)

Then install the plugins:

# In Claude Code:
/plugin marketplace add Threading-Needles/awl
/plugin install awl-dev

# Restart Claude Code

You're ready! Try /awl-dev:research-codebase in your next session.

Recommended: Add the Awl workflow snippet to your project's CLAUDE.md. See CLAUDE.md Setup for the copy-paste snippet.

See QUICKSTART.md for detailed setup instructions.

Installation

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