clue

When you have so many Claude sessions that you don't have a clue what you're working on.

clue is a workspace context manager for Claude Code that keeps track of your goals, notes, and progress across multiple conversations in the same workspace.

The Problem

You're deep into a complex feature. You've had 5 Claude conversations today, each touching different parts of the codebase. You start a new session and... what was I working on? What did I decide? What's left to do?

The Solution

clue gives you a persistent context that shows up right in Claude Code's status line:

────────────────────────────────────────────────────────────────────────
> help me implement the token refresh logic
────────────────────────────────────────────────────────────────────────
  [oauth-migration] implement refresh token rotation (2h ago)
  [claude ee14c03d] fix the token expiry edge case
  [note 3] Need to update the refresh token tests (1h ago - 4 notes)
  [git backend] feature/oauth* "add token rotation endpoint"

Every Claude conversation in your workspace sees this context. Set goals per-workspace or per-conversation. Take notes. Track progress.

Quick Start

# Install
git clone git@github.com:getnexar/clue.git
cd clue && make install

# Enable Claude status line integration
clue setup

Creating a Workspace

From Natural Language

Let clue generate a workspace name from your description:

clue create "migrating authentication from JWT to OAuth2"
# Creates: jwt-to-oauth2/
# Goal auto-set to your description

Initialize Existing Directory

Already have a project? Just init:

cd ~/projects/my-feature
clue init
clue w g "implement the new caching layer"  # or: clue workspace goal "..."

clue auto-discovers git repos in your workspace.

Goals

Workspace Goals

Set a goal that persists across all Claude sessions:

clue w g "implement refresh token rotation with automatic retry"
# or: clue workspace goal "..."

Per-Session Goals

Different Claude conversations can have different goals:

# See the session ID in the status line: [claude ee14c03d]
clue s g -s ee14c "fix the token expiry edge case"
# or: clue session goal -s ee14c "..."

Short IDs work like git - just enough characters to be unique.

Notes

Notes help you track what's done, what's pending, and what's important. You can manage notes directly from within a Claude Code session using the ! prefix to run shell commands:

Create Notes

────────────────────────────────────────────────────────────────────────
> ! clue n a "Need to update the refresh token tests"
────────────────────────────────────────────────────────────────────────

List Notes

────────────────────────────────────────────────────────────────────────
> ! clue n l
────────────────────────────────────────────────────────────────────────

Notes (3 notes, 1 pinned)
  [3] Need to update the refresh token tests (1h ago)
  [2] Redis is faster than DB for token storage (2h ago)
  [1] discovered we can reuse existing middleware (3h ago)

Strike Notes (Mark as Done)

────────────────────────────────────────────────────────────────────────
> ! clue n s 1
────────────────────────────────────────────────────────────────────────

Striked notes appear dimmed and at the bottom:

Notes (2 notes, 1 striked)
  [3] Need to update the refresh token tests (1h ago)
  [2] Redis is faster than DB for token storage (2h ago)
  [1] discovered we can reuse existing middleware (3h ago)  # dimmed, strikethrough

Pin Important Notes

────────────────────────────────────────────────────────────────────────
> ! clue n p 3
────────────────────────────────────────────────────────────────────────

Pinned notes are always visible in the Claude Code status line, appearing first and bold. Use this for notes you want Claude to see in every conversation.

Status Views

The default and --oneline formats are designed for the Claude Code status line. For a quick full overview in your terminal, just run clue (equivalent to clue w s -f).

Full Details (default for terminal)

clue
# or: clue w s -f
# or: clue workspace status --full

Workspace
  Name: oauth-migration (created 2d ago, updated 2h ago)
  Goal: implement refresh token rotation
  Directory: /home/user/workspaces/oauth-migration

Sessions (2)
  [claude ee14c03d] fix the token expiry edge case (current)
  [claude a1b2c3d4] initial OAuth setup

Repos
  [git backend] feature/oauth* "add token rotation endpoint"
    git@github.com:user/backend.git

Notes (3 notes, 1 pinned, 1 striked)
  [3] Need to update the refresh token tests (1h ago)
  [2] Redis is faster than DB for token storage (2h ago)
  [1] discovered we can reuse existing middleware (3h ago)

Compact (for Claude Code status line)

clue w s
# or: clue workspace status

[oauth-migration] implement refresh token rotation (2h ago)
[claude ee14c03d] fix the token expiry edge case
[note 3] Need to update the refresh token tests (1h ago - 4 notes)
[git backend] feature/oauth* "add token rotation endpoint"

One-line (for minimal status line)

clue w s -1
# or: clue workspace status --oneline

[oauth-migration] [note 3] Need to update... - [backend] feature/oauth* - 2h ago

Repository Management

Workspaces can track multiple git repositories:

# Clone a repo into the workspace
clue r a git@github.com:user/backend.git

# List repos with live git status
clue r l

# Scan for repos in workspace
clue r s

# Stop tracking (doesn't delete files)
clue r r backend

Installation

Manual

git clone git@github.com:getnexar/clue.git
cd clue
make install

This installs to ~/.local/bin. Make sure it's in your PATH.

Homebrew (coming soon)

brew tap getnexar/clue https://github.com/getnexar/clue.git
brew install clue

Claude Status Line Setup

Run the setup command:

clue setup

Or manually add to ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "clue status brief -c"
  }
}

Restart Claude Code to see the status line.

Commands Reference

clue uses an ip-style command hierarchy with single-letter shortcuts for faster typing.

Workspace Commands (workspace / w)

Command	Short	Description
workspace init [name]	w i	Initialize current directory as workspace
workspace create [-n name] [-j] <desc>	w c	Create workspace (AI names, -n override, -j JSON)
workspace goal [text]	w g	Set/show workspace goal
workspace name [text]	w n	Set/show workspace name

Note Commands (note / n)

Command	Short	Description
note add <text>	n a	Add a timestamped note
note list [-a]	n l	List all notes (-a includes striked)
note tip	n t	Get the tip (most recent active) note
note strike [-t|--tip] <id>	n s	Mark note as done (-t strikes tip note)
note unstrike <id>	n u	Unmark a striked note
note pin [-s [session-id]] <id>	n p	Pin note to show first (-s for session pinning)
note unpin [-s [session-id]] <id>	n z	Unpin a note (-s for session unpinning)

Session Commands (session / s)

Command	Short	Description
session add <session-id> [--goal <text>]	s a	Register a Claude session
session remove <session-id>	s r	Remove a Claude session
session goal [-s id] <text>	s g	Set goal for a Claude session
session show <id>	s s	Show session details
session list	s l	List all sessions

Status Commands (status)

Command	Description
status or status brief	Brief multi-line status (default)
status full	Full detailed status
status oneline	Single-line for status bar
(no command)	clue alone defaults to status full

All status commands support --json/-j and --all/-a options.

Repository Commands (repo / r)

Command	Short	Description
repo add <url> [subdir]	r a	Clone repository into workspace
repo list	r l	List repositories with git status
repo remove <path>	r r	Remove repository from tracking
repo scan	r s	Scan workspace for git repos

Other Commands

Command	Description
setup	Configure Claude status line integration
help	Show help
version	Show version

Options

Option	Description
-C <path>	Change to directory before running (git-style)
-d, --dir <path>	Specify workspace directory
--no-color	Disable color output
-h, --help	Show help
-v, --version	Show version

Data Format

Workspace data is stored in .clue/status.json:

{
  "version": "1.3",
  "name": "oauth-migration",
  "goal": "implement refresh token rotation",
  "created_at": "2025-12-19T10:30:00Z",
  "last_updated": "2025-12-19T15:45:00Z",
  "repos": [
    {"path": "backend", "remote": "git@github.com:user/backend.git"}
  ],
  "notes": {
    "1": {"timestamp": "2025-12-19T11:00:00Z", "text": "Started migration", "striked": true},
    "2": {"timestamp": "2025-12-19T14:30:00Z", "text": "Redis is faster", "pinned": true}
  },
  "sessions": {
    "ee14c03d-e988-4dff-8c5d-420270244d09": {
      "goal": "fix token expiry edge case",
      "transcript_path": "/home/user/.claude/projects/.../ee14c03d.jsonl",
      "created_at": "2025-12-19T15:00:00Z"
    }
  },
  "next_note_id": 3
}

Tips

Subdirectory Support

Run commands from any subdirectory - clue finds the workspace root:

cd ~/workspaces/oauth-migration/backend/src
clue n a "found the auth module"  # Works!

Multiple Workspaces

Switch context by changing directories:

cd ~/workspaces/oauth-migration && clue w s
cd ~/workspaces/perf-optimization && clue w s

Session Goals for Focused Work

Use session goals when one conversation has a specific sub-task:

# Main workspace goal: "implement OAuth migration"
# This session's focus:
clue s g -s ee14c "debug the refresh token rotation"

Dependencies

• jq - JSON processing (required)
• git - For repository management
• claude - Only for create command (AI name generation)

License

MIT