Skip to content

cub capture

Quickly capture ideas, notes, and observations for later processing into tasks.

Synopsis

cub capture [OPTIONS] [CONTENT]

Description

The cub capture command provides a fast way to record ideas, bugs, notes, and observations without interrupting your flow. Captures are saved as markdown files with frontmatter metadata for later organization.

Two-tier storage model:

  • Global captures (default): Stored at ~/.local/share/cub/captures/{project}/. These survive branch deletion and switching.
  • Project captures: Stored in ./captures/ when using --project. These are version-controlled with your repository.

Captures can later be:

Arguments

Argument Description
CONTENT Text to capture. If not provided, reads from stdin.

Options

Option Short Description
--tag TAG -t Add tag to capture (repeatable)
--name NAME -n Explicit filename (without .md extension)
--priority LEVEL -p Priority level (1-5, lower is higher priority)
--project -P Save to project captures directory instead of global
--interactive -i Launch interactive capture session with Claude
--no-auto-tags Disable automatic tag suggestion based on content
--no-slug Skip AI-generated slug, use ID as filename
--help -h Show help message and exit

Tags and Categorization

Manual Tags

Add tags explicitly with the --tag option:

cub capture "Add dark mode" --tag feature --tag ui

Tags help you filter and organize captures later.

Automatic Tag Suggestion

By default, cub analyzes your capture content and suggests relevant tags automatically. Common auto-suggested tags include:

Tag Detected From
feature "add", "implement", "new"
bug "fix", "broken", "error"
refactor "refactor", "cleanup", "reorganize"
docs "document", "readme", "guide"
test "test", "spec", "coverage"

Disable auto-tagging with --no-auto-tags.

Filename Generation

Captures are saved with descriptive filenames:

Format: {project}-cap-{YYYYMMDD}-{slug}.md

Example: myproject-cap-20260117-add-dark-mode-ui.md

The slug is generated by AI from your capture content. Use --name to specify an explicit name, or --no-slug to use just the ID.

Interactive Mode

Launch an AI-assisted capture session:

cub capture -i "New feature idea"

This opens Claude with the /cub:capture skill for guided exploration of your idea. The AI helps you:

  • Clarify the scope and goals
  • Identify edge cases
  • Break down complex ideas
  • Suggest related considerations

Requires Claude Code to be installed.

Capture File Format

Captures are stored as markdown files with YAML frontmatter:

---
id: cap-042
created: 2026-01-17T10:30:00Z
title: Add dark mode to UI
tags:
  - feature
  - ui
source: cli
priority: 2
status: active
---

The app should support a dark color scheme that users can toggle
in settings. This improves usability in low-light conditions.

Examples

Quick capture from command line

cub capture "Add dark mode to UI"

Output: 

[check] Captured as cap-042 (global)
  ~/.local/share/cub/captures/myproject/myproject-cap-20260117-add-dark-mode-ui.md

Capture with tags

cub capture "Refactor auth flow" --tag feature --tag auth

Capture with priority

cub capture "Critical bug in login" --tag bug --priority 1

Pipe content from another command

echo "Meeting notes: discussed Q1 roadmap" | cub capture

Multi-line capture from stdin

cat <<EOF | cub capture
Sprint planning notes:
- Focus on performance
- Address customer feedback
- Ship dark mode feature
EOF

Custom filename

cub capture --name "sprint-planning" "Q1 2026 sprint goals"

Save to project directory

cub capture --project "Ready for version control"

This saves to ./captures/ instead of the global store.

Interactive capture session

cub capture -i "New feature idea"

Opens Claude for guided exploration.

Disable auto-tagging

cub capture "Fix git merge bug" --no-auto-tags

Simple ID-based filename

cub capture "Quick note" --no-slug

Saves as cap-042.md instead of generating a descriptive filename.

Storage Locations

Global Store (Default)

~/.local/share/cub/captures/{project}/
  • Survives branch deletion
  • Organized by project automatically
  • Good for early-stage ideas

Project Store

./captures/
  • Version-controlled with repository
  • Use --project flag to save here
  • Good for team-shared captures

Workflow Integration

Capture-to-Task Pipeline

  1. Capture ideas as they come 

    cub capture "Improve error messages"

  2. Review captures periodically 

    cub captures

  3. Investigate to categorize 

    cub investigate --all

  4. Organize into tasks 

    cub organize-captures

Import to Project

Move important captures to version control:

cub captures import cap-042

See Also