bueller-wheel 0.2.0 → 0.3.1

package/README.md

@@ -1,6 +1,8 @@
 # Bueller Wheel
 
-A headless Claude Code issue processor that runs in a loop and resolves issues or ticket files written in markdown
+> Life moves pretty fast. If you don't stop and look around once in a while, you could miss it.
+
+This is a headless issue processor that runs in a loop and uses Claude to resolve issues or ticket files written in markdown. It plays nicely with Claude Code and uses the sames settings config.
 
 ## Quick Start
 
@@ -10,17 +12,17 @@ mkdir -p issues/open
 echo "@user: Please create a test file with 'Hello World'" > issues/open/p0-100-my-task.md
 
 # Run bueller-wheel to complete the task
-npx bueller-wheel
+npx bueller-wheel --run
 ```
 
 ## Why?
 
-You want Claude Code to autonomously work on a large pile of issues while you eat lunch and watch a baseball game. Bueller Wheel helps tackle several issues you might encounter:
+You want Claude to autonomously work on a large pile of issues while you go on a day trip into the city. Bueller Wheel helps tackle several issues you might encounter:
 
-- **Claude stops processing after a few issues**: Claude Code tends to stop processing after completing a few tasks. Bueller Wheel keeps prompting Claude Code to work until all of the issues have been resolved.
-- **Claude forgets what it's doing**: As Claude Code uses up its context window, it tends to forget what it was working on. Bueller Wheel runs Claude Code with a fresh context window and prompt for each issue.
-- **You forget what Claude was doing**: If you successfully get Claude Code to work on a large number of tasks, you end up with a pile of code to review. Bueller Wheel structures each issue as a discrete reviewable chunk of work, in a format amenable to multiple iterations of feedback between you and Claude.
-- **Claude keeps making the same mistakes**: A Claude that forgets its history is doomed to repeat it. Bueller Wheel sets up an FAQ directory for Claude to speed up resolution of frequent pitfalls.
+- **Claude stops processing after a few issues**: Claude tends to stop processing after completing a few tasks. Bueller Wheel keeps prompting Claude to work until all of the issues have been resolved.
+- **Claude forgets what it's doing**: As Claude uses up its context window, it tends to forget what it was working on. Bueller Wheel runs Claude with a fresh context window and prompt for each issue.
+- **You forget what Claude was doing**: If you successfully get Claude to work on a large number of tasks, you end up with a pile of code to review. Bueller Wheel structures each issue as a discrete reviewable chunk of work, in a format amenable to multiple iterations of feedback between you and Claude.
+- **Claude keeps making the same mistakes**: An agent that forgets its history is doomed to repeat it. Bueller Wheel sets up an FAQ directory for Claude to speed up resolution of frequent pitfalls.
 
 **Note**: Bueller Wheel is not a full-fledged task management system. It has no concept of assignment or dependency apart from linear file ordering. The sweet spot for this tool is **solo developers working on a single branch**. That said, you can make [parallel branches and agents](#working-with-multiple-branches) work.
 
@@ -29,7 +31,7 @@ You want Claude Code to autonomously work on a large pile of issues while you ea
 **The Processing Loop**
 
 1. Bueller Wheel finds the next issue in `issues/open/` (sorted alphabetically by filename)
-2. Claude Code reads the issue and works on the task
+2. Claude reads the issue and works on the task
 3. Claude appends its work summary to the issue file
 4. Claude decides the outcome:
    - **CONTINUE**: Keep working (stays in `open/`)
@@ -43,7 +45,7 @@ You want Claude Code to autonomously work on a large pile of issues while you ea
 - Move issues from `review/` or `stuck/` back to `open/` if more work is required
 - Delete issues from `review/` when done reviewing, or archive them however you want
 
-**Each iteration is a fresh Claude Code session** - no memory between iterations, which keeps context focused.
+**Each iteration is a fresh Claude session** - no memory between iterations, which keeps context focused.
 
 **Inherits your project's Claude Code setup** - `bueller-wheel` uses the Anthropic API credential from whichever user you're logged in as. It inherits the same `.claude/settings.json` or `.claude/settings.local.json` as the Claude Code project it's used in. Whatever permissions apply to your regular `claude` CLI should also apply to `bueller-wheel`, with the exception that `bueller-wheel` starts in "accept edits" mode.
 
@@ -137,18 +139,37 @@ The `open/` directory acts as an inbox for the agent on the current branch. The
 ## CLI Options
 
 ```bash
-npx bueller-wheel --issues-dir ./my-issues --faq-dir ./my-faq --max-iterations 50 --git-commit --prompt ./my-prompt.md
+# Start the agent loop with various options
+npx bueller-wheel --run
+npx bueller-wheel --git
+npx bueller-wheel --max 50
+npx bueller-wheel --continue "fix the bug"
+
+# Summarize issues
+npx bueller-wheel --summarize p1-003-task.md
+npx bueller-wheel --summarize p1-003.md p2-005.md --index 1
+
+# Combine with other options
+npx bueller-wheel --run --issues-dir ./my-issues --faq-dir ./my-faq
+npx bueller-wheel --max 50 --git --prompt ./my-prompt.md
 
 # Or if installed globally
-bueller-wheel --issues-dir ./my-issues --faq-dir ./my-faq --max-iterations 50 --git-commit --prompt ./my-prompt.md
+bueller-wheel --run
+bueller-wheel --git
 ```
 
+**Run Commands** (one required):
+- `--run`: Explicitly start the agent loop with defaults
+- `--git`: Enable automatic git commits and start the loop
+- `--max <number>`: Start with maximum N iterations (default: `25`)
+- `--continue [prompt]`: Continue from previous session. Optional prompt defaults to "continue" if not provided
+- `--summarize <issue...>`: Display abbreviated summaries of issue conversation history
+
+**Configuration Options**:
 - `--issues-dir <path>`: Issues directory (default: `./issues`)
 - `--faq-dir <path>`: FAQ directory (default: `./faq`)
-- `--max-iterations <number>`: Maximum iterations (default: `25`)
-- `--git-commit`: Enable automatic git commits after each iteration (default: disabled)
 - `--prompt <path>`: Path to custom prompt template file (default: `<issues-dir>/prompt.md`)
-- `--continue [prompt]`: Continue from previous session. Optional prompt defaults to "continue" if not provided
+- `--index <N>` or `--index <M,N>`: Expand specific messages when using `--summarize` (see below)
 
 ### Custom Prompt Templates
 
@@ -210,7 +231,7 @@ Note that only the immediate prior iteration is continued. The next iteration wi
 
 ### Git Auto-Commit
 
-When `--git-commit` is enabled, Bueller Wheel will automatically create a git commit after each iteration where work was done on an issue.
+When `--git` is enabled, Bueller Wheel will automatically create a git commit after each iteration where work was done on an issue.
 
 The commit message format includes the issue ID (the filename minus the `.md`) and status:
 ```
@@ -219,13 +240,68 @@ p0-002-git in progress
 p0-002-git stuck
 p0-002-git unknown
 ```
+
+### Issue Summarization
+
+The `--summarize` command provides a quick way to review issue conversation history without opening files. This is especially useful for:
+- Quickly understanding what happened in an issue
+- Reviewing multiple issues at once
+- Checking the status and progress of work
+
+**Basic Usage:**
+
+```bash
+# Summarize a single issue (by filename - searches across open/, review/, stuck/)
+npx bueller-wheel --summarize p1-003-task.md
+
+# Summarize by partial filename
+npx bueller-wheel --summarize p1-003.md
+
+# Summarize with full path
+npx bueller-wheel --summarize /path/to/issues/open/p1-003-task.md
+
+# Summarize multiple issues
+npx bueller-wheel --summarize p1-003.md p1-004.md p2-001.md
+```
+
+**Summary Format:**
+
+By default, summaries show:
+- Issue filename and status (open/review/stuck)
+- First message: up to 300 characters
+- Middle messages: up to 80 characters each (abbreviated)
+- Last message: up to 300 characters
+
+**Expanding Messages:**
+
+Use `--index` to expand specific messages to their full content:
+
+```bash
+# Expand a single message at index 2
+npx bueller-wheel --summarize p1-003.md --index 2
+
+# Expand a range of messages (indices 1 through 3)
+npx bueller-wheel --summarize p1-003.md --index 1,3
+
+# Works with multiple issues (expands same indices for all)
+npx bueller-wheel --summarize p1-003.md p1-004.md --index 0,2
+```
+
+**Note:** Message indices are 0-based (first message is index 0).
+
 ## Development
 
-`pnpm run dev` will execute the current `src/index.ts` script file with whatever args you pass to it.
+`pnpm run dev` will execute the current `src/index.ts` script file with whatever args you pass to it. For example:
+
+```bash
+pnpm run dev -- --run
+pnpm run dev -- --git
+pnpm run dev -- --max 10
+```
 
 ## End-to-End Testing
 
-**These tests use your actual live instance of Claude Code!**
+**These tests use your actual Anthropic / Claude credentials!**
 
 ```bash
 # Run all tests

package/dist/index.js

@@ -3,6 +3,7 @@ import { execSync } from 'node:child_process';
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import { query } from '@anthropic-ai/claude-agent-sdk';
+import { expandMessages, formatIssueSummary, resolveIssueReference, summarizeIssue, } from './issue-summarize.js';
 // Colors for output
 const colors = {
     red: '\x1b[0;31m',
@@ -17,19 +18,27 @@ const ISSUE_DIR_REVIEW = 'review';
 const ISSUE_DIR_STUCK = 'stuck';
 function showHelp() {
     console.log(`
-Bueller - Headless Claude Code Issue Processor
+Bueller Wheel - Headless Claude Code Issue Processor
 
 USAGE:
-  bueller [OPTIONS]
+  bueller-wheel run [OPTIONS]               Start the agent loop
+  bueller-wheel issue ISSUE... [OPTIONS]    View issue summaries
+
+COMMANDS:
+  run                 Start the agent loop to process issues
+  issue ISSUE...      Summarize one or more issues (accepts file paths or filenames)
 
 OPTIONS:
   --help              Show this help message and exit
+  --git               Enable automatic git commits (on by default, run command only)
+  --no-git            Disable automatic git commits (run command only)
+  --max N             Maximum number of iterations to run (default: 25, run command only)
+  --continue [PROMPT] Continue from previous session (default prompt: "continue", run command only)
+  --index N           Expand message at index N (issue command only)
+  --index M,N         Expand message range from M to N (issue command only)
   --issues-dir DIR    Directory containing issue queue (default: ./issues)
   --faq-dir DIR       Directory containing FAQ/troubleshooting guides (default: ./faq)
-  --max-iterations N  Maximum number of iterations to run (default: 25)
-  --git, --git-commit Enable automatic git commits after each iteration
-  --prompt FILE       Custom prompt template file (default: ./issues/prompt.md)
-  --continue [PROMPT] Continue from previous session (default prompt: "continue")
+  --prompt FILE       Custom prompt template file (default: ./issues/prompt.md, run command only)
 
 DIRECTORY STRUCTURE:
   issues/
@@ -48,10 +57,14 @@ ISSUE FILE FORMAT:
     p2: Non-blocking follow-up
 
 EXAMPLES:
-  bueller
-  bueller --issues-dir ./my-issues --faq-dir ./my-faq
-  bueller --max-iterations 50 --git-commit
-  bueller --prompt ./custom-prompt.md
+  bueller-wheel run
+  bueller-wheel run --no-git
+  bueller-wheel run --max 50
+  bueller-wheel run --continue "fix the bug"
+  bueller-wheel run --issues-dir ./my-issues --faq-dir ./my-faq
+  bueller-wheel issue p1-003-read-helper-002.md
+  bueller-wheel issue p1-003 p2-005 --index 1
+  bueller-wheel issue /path/to/issue.md --index 0,2
 
 For more information, visit: https://github.com/anthropics/bueller
 `);
@@ -59,18 +72,52 @@ For more information, visit: https://github.com/anthropics/bueller
 function parseArgs() {
     const args = process.argv.slice(2);
     // Check for help flag first
-    if (args.includes('--help') || args.includes('-h')) {
+    if (args.includes('--help') || args.includes('-h') || args.length === 0) {
         showHelp();
         process.exit(0);
     }
+    // First argument should be the command
+    const command = args[0];
+    if (command !== 'run' && command !== 'issue') {
+        console.error(`${colors.red}Error: Unknown command "${command}". Use "run" or "issue".${colors.reset}\n`);
+        showHelp();
+        process.exit(1);
+    }
+    // Define recognized flags
+    const recognizedFlags = new Set([
+        '--issues-dir',
+        '--faq-dir',
+        '--max',
+        '--git',
+        '--no-git',
+        '--prompt',
+        '--continue',
+        '--index',
+        '--help',
+        '-h',
+    ]);
+    // Check for unrecognized flags
+    for (const arg of args.slice(1)) {
+        // Check if this looks like a flag (starts with -)
+        if (arg.startsWith('-')) {
+            if (!recognizedFlags.has(arg)) {
+                console.error(`${colors.red}Error: Unrecognized flag: ${arg}${colors.reset}\n`);
+                showHelp();
+                process.exit(1);
+            }
+        }
+    }
     let issuesDir = './issues';
     let faqDir = './faq';
     let maxIterations = 25;
-    let gitCommit = false;
+    let gitCommit = true;
     let promptFile = path.join('./issues', 'prompt.md');
     let continueMode = false;
     let continuePrompt = 'continue';
-    for (let i = 0; i < args.length; i++) {
+    const issueReferences = [];
+    let issueIndex;
+    // Parse arguments starting from index 1 (skip the command)
+    for (let i = 1; i < args.length; i++) {
         if (args[i] === '--issues-dir' && i + 1 < args.length) {
             issuesDir = args[++i];
             // Update default prompt file location if issues-dir is changed
@@ -81,12 +128,15 @@ function parseArgs() {
         else if (args[i] === '--faq-dir' && i + 1 < args.length) {
             faqDir = args[++i];
         }
-        else if (args[i] === '--max-iterations' && i + 1 < args.length) {
+        else if (args[i] === '--max' && i + 1 < args.length) {
             maxIterations = parseInt(args[++i], 10);
         }
-        else if (args[i] === '--git' || args[i] === '--git-commit') {
+        else if (args[i] === '--git') {
             gitCommit = true;
         }
+        else if (args[i] === '--no-git') {
+            gitCommit = false;
+        }
         else if (args[i] === '--prompt' && i + 1 < args.length) {
             promptFile = args[++i];
         }
@@ -97,6 +147,21 @@ function parseArgs() {
                 continuePrompt = args[++i];
             }
         }
+        else if (args[i] === '--index' && i + 1 < args.length) {
+            issueIndex = args[++i];
+        }
+        else if (!args[i].startsWith('--')) {
+            // Non-flag argument - collect as issue reference for issue command
+            if (command === 'issue') {
+                issueReferences.push(args[i]);
+            }
+        }
+    }
+    // Validate issue command
+    if (command === 'issue' && issueReferences.length === 0) {
+        console.error(`${colors.red}Error: "issue" command requires at least one issue reference.${colors.reset}\n`);
+        showHelp();
+        process.exit(1);
     }
     return {
         issuesDir,
@@ -106,6 +171,9 @@ function parseArgs() {
         promptFile,
         continueMode,
         continuePrompt,
+        command: command,
+        issueReferences,
+        issueIndex,
     };
 }
 async function ensureDirectories(issuesDir, faqDir) {
@@ -214,9 +282,16 @@ Here is a summary of the work I have done:
 
 Your issue file: [ISSUE_FILE_PATH]
 
+Issue files may be long. Use CLI commands to read:
+- To summarize: \`npx bueller-wheel issue [ISSUE_FILE_PATH]\`
+- To expand: \`npx bueller-wheel issue [ISSUE_FILE_PATH] --index <start>,<end>\`
+
 1. **Read the issue**: Parse the conversation history in [ISSUE_FILE_PATH] to understand the task
 2. **Work on the task**: Do what the issue requests. When encountering issues, always check for a relevant guide in [FAQ_DIR]/ first.
-3. **Append your response**: Add your summary to [ISSUE_FILE_PATH] using this format:
+3. **Verify**: Verify the following pass:
+   - [ ] \`pnpm run lint:fix\`
+   - [ ] \`pnpm run typecheck\`
+4. **Append your response**: Add your summary to [ISSUE_FILE_PATH] using this format:
    \`\`\`
    ---
 
@@ -228,7 +303,7 @@ Your issue file: [ISSUE_FILE_PATH]
    - Item 3
    \`\`\`
 
-4. **Decide the outcome**: Choose ONE of the following actions:
+5. **Decide the outcome**: Choose ONE of the following actions:
 
    a. **CONTINUE** - You made progress but the task isn't complete yet
       - Leave the issue in \`[ISSUES_DIR]/[ISSUE_DIR_OPEN]/\` for the next iteration
@@ -259,6 +334,10 @@ Your issue file: [ISSUE_FILE_PATH]
 
 **Critical:** ALWAYS check the FAQ directory ([FAQ_DIR]/) to see if there is a guide when you encounter a problem.
 
+## Adding to the FAQ
+
+Consider adding a **CONCISE** FAQ in [FAQ_DIR]/ for non-obvious solutions, recurring issues, or multi-step troubleshooting that would help future agents. Skip trivial/one-off problems or topics already documented.
+
 Now, please process the issue at [ISSUE_FILE_PATH].`;
 }
 async function loadOrCreatePromptTemplate(promptFile) {
@@ -314,12 +393,16 @@ function logToolUse(block) {
         case 'grep': {
             const pattern = block.input?.pattern;
             const glob = block.input?.glob;
+            const path = block.input?.path;
             if (pattern) {
                 process.stdout.write(`${pattern}`);
             }
             if (glob) {
                 process.stdout.write(` (${glob})`);
             }
+            if (path) {
+                process.stdout.write(` (${path})`);
+            }
             break;
         }
         case 'todowrite': {
@@ -388,6 +471,13 @@ async function runAgent(options) {
             settingSources: ['local', 'project', 'user'],
             permissionMode: 'acceptEdits',
             continue: continueMode,
+            canUseTool: async (toolName, input) => {
+                console.log(`${colors.red}Auto-denied tool:${colors.reset} ${toolName} ${String(input?.['command'] ?? input?.['file_path'] ?? '')}`);
+                return {
+                    behavior: 'deny',
+                    message: `You are running autonomously. The user cannot grant permission. Find a workaround or mark the issue as stuck. Check ${faqDir}/ to see if this is covered.`,
+                };
+            },
         },
     });
     for await (const item of stream) {
@@ -395,8 +485,39 @@ async function runAgent(options) {
     }
     console.log(`${colors.blue}\n--- Agent finished ---${colors.reset}`);
 }
+async function runIssue(config) {
+    for (const issueRef of config.issueReferences) {
+        // Normalize issue reference - add .md extension if missing
+        let normalizedRef = issueRef;
+        if (!issueRef.endsWith('.md')) {
+            normalizedRef = `${issueRef}.md`;
+        }
+        const located = await resolveIssueReference(normalizedRef, config.issuesDir);
+        if (!located) {
+            console.error(`${colors.red}Error: Could not find issue: ${issueRef}${colors.reset}\n`);
+            continue;
+        }
+        try {
+            let summary = await summarizeIssue(located);
+            // Apply index expansion if specified
+            if (config.issueIndex) {
+                summary = expandMessages(summary, config.issueIndex);
+            }
+            const formatted = formatIssueSummary(summary, config.issueIndex);
+            console.log(formatted);
+        }
+        catch (error) {
+            console.error(`${colors.red}Error summarizing ${issueRef}: ${String(error)}${colors.reset}\n`);
+        }
+    }
+}
 async function main() {
     const config = parseArgs();
+    // Handle issue command
+    if (config.command === 'issue') {
+        await runIssue(config);
+        return;
+    }
     console.log(`${colors.cyan}Bueller? Bueller?${colors.reset}`);
     console.log(`${colors.cyan}-----------------${colors.reset}`);
     console.log(`Issues directory: ${config.issuesDir}`);
@@ -422,12 +543,14 @@ async function main() {
         console.log(`Found ${openIssues.length} open issue(s)`);
         console.log(`Next issue: ${openIssues[0]}`);
         const currentIssue = openIssues[0];
+        // Only use continue mode on the first iteration
+        const isFirstIteration = iteration === 1;
         await runAgent({
             template: promptTemplate,
             issuesDir: config.issuesDir,
             faqDir: config.faqDir,
             issueFile: currentIssue,
-            continueMode: config.continueMode,
+            continueMode: config.continueMode && isFirstIteration,
             continuePrompt: config.continuePrompt,
         });
         // Auto-commit if enabled and there's a current issue

package/dist/issue-reader.js

@@ -0,0 +1,92 @@
+import * as fs from 'node:fs/promises';
+/**
+ * Parses an issue markdown file and extracts the conversation history
+ *
+ * @param filePath - Absolute path to the issue file
+ * @returns Parsed issue with message history
+ * @throws Error if file cannot be read or if the format is invalid
+ */
+export async function readIssue(filePath) {
+    let rawContent;
+    try {
+        rawContent = await fs.readFile(filePath, 'utf-8');
+    }
+    catch (error) {
+        throw new Error(`Failed to read issue file at ${filePath}: ${String(error)}`);
+    }
+    return parseIssueContent(rawContent);
+}
+/**
+ * Parses issue content and extracts the conversation history
+ *
+ * @param content - Raw markdown content of the issue file
+ * @returns Parsed issue with message history
+ */
+export function parseIssueContent(content) {
+    const messages = [];
+    // Split by the separator (---)
+    const sections = content.split(/\n---\n/);
+    let messageIndex = 0;
+    for (const section of sections) {
+        const trimmedSection = section.trim();
+        // Skip empty sections
+        if (!trimmedSection) {
+            continue;
+        }
+        // Check if this section starts with @user: or @claude:
+        const userMatch = trimmedSection.match(/^@user:\s*([\s\S]*)$/);
+        const claudeMatch = trimmedSection.match(/^@claude:\s*([\s\S]*)$/);
+        if (userMatch) {
+            messages.push({
+                index: messageIndex++,
+                author: 'user',
+                content: userMatch[1].trim(),
+            });
+        }
+        else if (claudeMatch) {
+            messages.push({
+                index: messageIndex++,
+                author: 'claude',
+                content: claudeMatch[1].trim(),
+            });
+        }
+        // If no match, skip this section (handles malformed sections)
+    }
+    return {
+        messages,
+        rawContent: content,
+    };
+}
+/**
+ * Gets the latest message from an issue
+ *
+ * @param issue - Parsed issue object
+ * @returns The most recent message, or undefined if no messages exist
+ */
+export function getLatestMessage(issue) {
+    if (issue.messages.length === 0) {
+        return undefined;
+    }
+    return issue.messages[issue.messages.length - 1];
+}
+/**
+ * Gets all messages from a specific author
+ *
+ * @param issue - Parsed issue object
+ * @param author - Author to filter by ('user' or 'claude')
+ * @returns Array of messages from the specified author
+ */
+export function getMessagesByAuthor(issue, author) {
+    return issue.messages.filter((msg) => msg.author === author);
+}
+/**
+ * Formats a message for appending to an issue file
+ *
+ * @param author - Author of the message ('user' or 'claude')
+ * @param content - Content of the message
+ * @returns Formatted message string ready to append to an issue file
+ */
+export function formatMessage(author, content) {
+    return `---\n\n@${author}: ${content}`;
+}
+//# sourceMappingURL=issue-reader.js.map

package/dist/issue-summarize.js

@@ -0,0 +1,236 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { parseIssueContent } from './issue-reader.js';
+/**
+ * Searches for an issue file by filename across the issue directories
+ *
+ * @param filename - The issue filename (e.g., "p1-003-read-helper-002.md")
+ * @param issuesDir - Base issues directory
+ * @returns Located issue or null if not found
+ */
+export async function locateIssueFile(filename, issuesDir) {
+    const directories = [
+        { dir: path.join(issuesDir, 'open'), status: 'open' },
+        { dir: path.join(issuesDir, 'review'), status: 'review' },
+        { dir: path.join(issuesDir, 'stuck'), status: 'stuck' },
+    ];
+    for (const { dir, status } of directories) {
+        const filePath = path.join(dir, filename);
+        try {
+            await fs.access(filePath);
+            return {
+                filePath,
+                status,
+                filename,
+            };
+        }
+        catch {
+            // File doesn't exist in this directory, continue searching
+        }
+    }
+    return null;
+}
+/**
+ * Resolves an issue reference (either a full path or filename) to a located issue
+ *
+ * @param reference - File path or filename
+ * @param issuesDir - Base issues directory
+ * @returns Located issue or null if not found
+ */
+export async function resolveIssueReference(reference, issuesDir) {
+    // Check if it looks like a path (contains path separators)
+    if (reference.includes('/') || reference.includes('\\')) {
+        // Treat as a file path (absolute or relative)
+        const absolutePath = path.isAbsolute(reference) ? reference : path.resolve(reference);
+        try {
+            await fs.access(absolutePath);
+            // Determine status from path
+            let status = 'open';
+            if (absolutePath.includes('/review/')) {
+                status = 'review';
+            }
+            else if (absolutePath.includes('/stuck/')) {
+                status = 'stuck';
+            }
+            return {
+                filePath: absolutePath,
+                status,
+                filename: path.basename(absolutePath),
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    // Otherwise, treat it as a filename and search for it
+    return locateIssueFile(reference, issuesDir);
+}
+/**
+ * Abbreviates a message based on its position in the conversation
+ *
+ * @param message - The message to abbreviate
+ * @param _position - Position in conversation ('first', 'middle', or 'last')
+ * @param maxLength - Maximum length for the abbreviated content
+ * @returns Abbreviated message
+ */
+function abbreviateMessage(message, _position, maxLength) {
+    const fullContent = message.content;
+    let abbreviated = fullContent;
+    let isAbbreviated = false;
+    if (fullContent.length > maxLength) {
+        abbreviated = fullContent.substring(0, maxLength).trimEnd() + '…';
+        isAbbreviated = true;
+    }
+    return {
+        index: message.index,
+        author: message.author,
+        content: abbreviated,
+        isAbbreviated,
+        fullContent,
+    };
+}
+/**
+ * Creates abbreviated messages from a parsed issue
+ *
+ * @param messages - Array of issue messages
+ * @returns Array of abbreviated messages
+ */
+function createAbbreviatedMessages(messages) {
+    if (messages.length === 0) {
+        return [];
+    }
+    if (messages.length === 1) {
+        // Single message - use 230 char limit
+        return [abbreviateMessage(messages[0], 'first', 230)];
+    }
+    const result = [];
+    // First message - 230 chars
+    result.push(abbreviateMessage(messages[0], 'first', 230));
+    // Middle messages - 70 chars
+    for (let i = 1; i < messages.length - 1; i++) {
+        result.push(abbreviateMessage(messages[i], 'middle', 70));
+    }
+    // Last message - 230 chars
+    result.push(abbreviateMessage(messages[messages.length - 1], 'last', 230));
+    return result;
+}
+/**
+ * Summarizes an issue file with abbreviated messages
+ *
+ * @param locatedIssue - Located issue information
+ * @returns Issue summary
+ */
+export async function summarizeIssue(locatedIssue) {
+    const content = await fs.readFile(locatedIssue.filePath, 'utf-8');
+    const parsed = parseIssueContent(content);
+    const abbreviatedMessages = createAbbreviatedMessages(parsed.messages);
+    return {
+        issue: locatedIssue,
+        abbreviatedMessages,
+        messageCount: parsed.messages.length,
+    };
+}
+/**
+ * Parses index specification (e.g., "3" or "1,3")
+ *
+ * @param indexSpec - Index specification string
+ * @returns Object with indices array and whether it's a single index, or null if invalid
+ */
+export function parseIndexSpec(indexSpec) {
+    const parts = indexSpec.split(',').map((s) => s.trim());
+    if (parts.length === 1) {
+        // Single index
+        const index = parseInt(parts[0], 10);
+        if (isNaN(index) || index < 0) {
+            return null;
+        }
+        return { indices: [index], isSingleIndex: true };
+    }
+    if (parts.length === 2) {
+        // Range
+        const start = parseInt(parts[0], 10);
+        const end = parseInt(parts[1], 10);
+        if (isNaN(start) || isNaN(end) || start < 0 || end < start) {
+            return null;
+        }
+        const indices = [];
+        for (let i = start; i <= end; i++) {
+            indices.push(i);
+        }
+        return { indices, isSingleIndex: false };
+    }
+    return null;
+}
+/**
+ * Expands specific messages in a summary based on index specification
+ *
+ * @param summary - Issue summary
+ * @param indexSpec - Index specification (e.g., "3" or "1,3")
+ * @returns New summary with expanded messages and filter info
+ */
+export function expandMessages(summary, indexSpec) {
+    const parsed = parseIndexSpec(indexSpec);
+    if (!parsed) {
+        return summary;
+    }
+    const { indices, isSingleIndex } = parsed;
+    const expandedMessages = summary.abbreviatedMessages.map((msg) => {
+        if (indices.includes(msg.index)) {
+            return {
+                ...msg,
+                content: msg.fullContent,
+                isAbbreviated: false,
+            };
+        }
+        return msg;
+    });
+    return {
+        ...summary,
+        abbreviatedMessages: expandedMessages,
+        filterToIndices: indices,
+        isSingleIndex,
+    };
+}
+/**
+ * Condenses text by trimming lines and replacing newlines with single spaces
+ *
+ * @param text - Text to condense
+ * @returns Condensed text
+ */
+function condenseText(text) {
+    return text
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .join(' ');
+}
+/**
+ * Formats an issue summary for console output
+ *
+ * @param summary - Issue summary (may include filterToIndices and isSingleIndex)
+ * @param indexSpec - Optional index specification for filtering display
+ * @returns Formatted string
+ */
+export function formatIssueSummary(summary, indexSpec) {
+    const lines = [];
+    // Header
+    const directory = `${summary.issue.status}/`;
+    const filename = summary.issue.filename;
+    lines.push(`${directory}${filename}`);
+    // Determine which messages to show
+    const messagesToShow = summary.filterToIndices
+        ? summary.abbreviatedMessages.filter((msg) => summary.filterToIndices.includes(msg.index))
+        : summary.abbreviatedMessages;
+    // Messages
+    for (const msg of messagesToShow) {
+        const content = msg.isAbbreviated ? condenseText(msg.content) : msg.content;
+        lines.push(`[${msg.index}] @${msg.author}: ${content}`);
+    }
+    // Add follow-up action hint if not showing specific indices
+    if (!indexSpec || !summary.isSingleIndex) {
+        lines.push('');
+        lines.push('Pass `--index N` or `--index M,N` to see more.');
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=issue-summarize.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "bueller-wheel",
-	"version": "0.2.0",
+	"version": "0.3.1",
 	"description": "Headless Claude Code issue processor - A wrapper that runs Claude Code in a loop to process issues from a directory queue",
 	"type": "module",
 	"main": "dist/index.js",
@@ -8,7 +8,7 @@
 		"bueller-wheel": "dist/index.js"
 	},
 	"scripts": {
-		"build": "rm -rf dist out && tsc && mkdir -p dist && cp out/src/index.js dist/index.js && echo '#!/usr/bin/env node' | cat - dist/index.js > dist/index.tmp && mv dist/index.tmp dist/index.js && chmod +x dist/index.js",
+		"build": "rm -rf dist out && tsc && mkdir -p dist && cp out/src/*.js dist/ && echo '#!/usr/bin/env node' | cat - dist/index.js > dist/index.tmp && mv dist/index.tmp dist/index.js && chmod +x dist/index.js",
 		"dev": "tsx src/index.ts",
 		"start": "node dist/index.js",
 		"test": "tsx tests/test-runner.ts",
@@ -37,7 +37,7 @@
 	},
 	"homepage": "https://github.com/fongandrew/bueller-wheel#readme",
 	"files": [
-		"dist/index.js",
+		"dist/*.js",
 		"README.md",
 		"LICENSE"
 	],