synap

A CLI for externalizing your working memory - capture ideas, projects, features, todos, and questions.


Features

- Quick Capture - Add ideas, todos, projects, and questions with minimal friction
- Agent-Ready - Built-in --json flag for AI agent integration
- Hierarchical Organization - Link entries as parent/child relationships
- Full-Text Search - Search content and tags across all entries
- Import/Export - Backup and restore your data in JSON or CSV format
- Claude Code Integration - Bundled skill teaches AI agents how to use the tool
- Safe Deletions - All deletions are logged and reversible with restore
- User Preferences (Memory) - Store agent-readable preferences for consistent behavior
- Setup Wizard - Guided first-run experience for new installs

Installation

``bash
npm install -g synap
`

Quick Start

`bash


Capture thoughts quickly

synap add "Research state management options for the new app"
synap todo "Review PR #42 before standup"
synap idea "What if we added dark mode?"
synap question "How does the auth flow work?"

See what needs attention

synap focus # P1 todos + active projects
synap list --status raw # Unprocessed entries

Organize and complete

synap set abc123 --status active --priority 1
synap done abc123

Search and explore

synap search "auth"
synap tree # Hierarchical view

First-run setup

synap setup
`

Commands

| Command | Description |
|---------|-------------|
| synap add | Quick capture (defaults to idea) |
| synap todo | Add a todo |
| synap question | Add a question |
| synap idea | Add an idea |
| synap project | Add a project |
| synap feature | Add a feature |
| synap note | Add a note |
| synap ref | Add a reference |
| synap list | List entries (with filters) |
| synap show | Show entry details |
| synap search | Full-text search |
| synap edit | Edit entry content |
| synap set | Update entry metadata |
| synap link | Link entries together |
| synap done | Mark entry as done |
| synap archive | Archive entry |
| synap delete | Delete entry (logged) |
| synap restore | Restore deleted entries |
| synap export | Export entries to file |
| synap import | Import entries from file |
| synap stats | Show statistics |
| synap tree [id] | Hierarchical view |
| synap focus | P1 todos + active projects |
| synap review [daily\|weekly] | Guided review session |
| synap triage | Interactive raw entry processing |
| synap config [key] [value] | View/update configuration |
| synap tags | List all tags with counts |
| synap tags rename | Rename tag across entries |
| synap install-skill | Install Claude Code skill |
| synap preferences | View or update user preferences |
| synap setup | Guided first-run wizard |

Run synap --help for detailed options.

$3

`bash


By type and status

synap list --type todo --status active
synap list --not-type reference

By tags

synap list --tags work,urgent
synap list --any-tags work,personal # OR logic
synap list --not-tags archived

By date

synap list --since 7d # Last 7 days
synap list --before 30d # Older than 30 days
synap list --between 2025-01-01,2025-01-31
`

Configuration

Configuration is stored at ~/.config/synap/config.json.

| Key | Default | Description |
|-----|---------|-------------|
| defaultType | idea | Default type for synap add |
| defaultTags | [] | Tags automatically added to new entries |
| editor | $EDITOR | Editor for synap edit |
| dateFormat | relative | Display format: relative, absolute, or locale |

`bash


View all config

synap config

Set a value

synap config defaultType todo
synap config dateFormat absolute
`

Claude Code Integration

This CLI includes a skill that teaches Claude Code how to use synap effectively.

`bash


Install the skill

synap install-skill

Uninstall

synap install-skill --uninstall
`

Once installed, Claude Code can help you:
- Capture ideas from conversations
- Review and triage your entries
- Organize projects hierarchically
- Generate daily/weekly reviews
- Follow your saved preferences from synap preferences

User Preferences (Memory)

Preferences are stored at ~/.config/synap/user-preferences.md and are readable by agents.

`bash


View preferences

synap preferences

Edit in $EDITOR

synap preferences --edit

Append to a section

synap preferences --append "## About Me" "I prefer concise summaries."

Reset to template

synap preferences --reset
`

Data Storage

All data is stored locally at ~/.config/synap/:

| File | Description |
|------|-------------|
| entries.json | Active entries |
| archive.json | Archived entries |
| deletion-log.json | Audit log for restore capability |
| config.json | User configuration |
| user-preferences.md | Agent-readable preferences |

Development

`bash


Clone and install

git clone https://github.com/yourusername/synap-cli.git
cd synap-cli
npm install

Run locally

node src/cli.js

Run tests

npm test # Watch mode
npm run test:run # Single run

Link for global use during development

npm link
``

Requirements: Node.js >= 18.0.0

License

MIT