npm package: @mwguerra/my-assistant
Description: Your intelligent productivity companion for software development - manage Claude Code sessions, tasks, ideas, and problems across all your projects
Author: Marcelo Guerra
Latest version: 0.2.0

# My Assistant

Your intelligent productivity companion for software development. Like having a personal secretary that keeps track of everything you're working on across all your projects.

## What It Does

**My Assistant** automatically tracks your Claude Code conversations and extracts actionable insights, while also letting you manage standalone projects, tasks, ideas, and problems. It's designed for developers who use Claude Code daily but want a unified view of their work.

### For Claude Code Users

- **Automatic Session Sync** - Captures all your Claude Code conversations automatically
- **Smart Extraction** - Identifies TODOs, problems, and ideas from your discussions
- **Session Summaries** - AI-generated summaries of what you accomplished
- **Conversation Search** - Find that solution you discussed weeks ago
- **Progress Tracking** - See what's being worked on across all projects

### For Any Project

- **Virtual Projects** - Create projects for work that isn't tied to Claude Code
- **Task Management** - Add todos with due dates, dependencies, and recurring schedules
- **Problem Tracking** - Document issues that need solving
- **Idea Capture** - Save ideas before they slip away
- **Time Tracking** - Track how long you spend on tasks
- **Daily Briefings** - Start each day knowing exactly what needs attention

## Installation

```bash
# Install globally with npm
npm install -g my-assistant

# Or with bun
bun install -g my-assistant
```

**Requirements:** [Bun](https://bun.sh/) runtime, [Claude Code](https://claude.ai/code) (optional, for session sync)

## Quick Start

```bash
# Initialize everything in one command
my-assistant init
```

This single command:
1. Checks all dependencies (Bun, Claude CLI, authentication, clipboard)
2. Creates the database and configures hourly automatic sync
3. Syncs all your Claude Code sessions
4. Generates AI summaries for all sessions

You're ready to go! Launch the TUI to explore:

```bash
my-assistant tui
```

## Daily Workflow Examples

### Morning Routine

```bash
# See what needs your attention today
my-assistant briefing

# Output:
# BRIEFING FOR THURSDAY, JANUARY 30
#
# OVERDUE (2)
#   #42 Fix authentication bug (my-app) - 2 days overdue
#   #38 Update API documentation (api-service) - 1 day overdue
#
# DUE TODAY (3)
#   #45 Review PR for new feature (my-app)
#   #47 Deploy staging environment (my-app)
#   #51 Team sync meeting notes (general)
#
# PROBLEMS REQUIRING ATTENTION (1)
#   #39 Memory leak in production (api-service)
```

### During Development

```bash
# Add a task you just thought of
my-assistant todo add my-app "Refactor user service" --due tomorrow

# Found a bug? Track it
my-assistant problem add my-app "Login fails with special characters in password"

# Had an idea? Capture it
my-assistant idea add my-app "Could use caching for frequently accessed data"

# Start tracking time on a task
my-assistant track start 42
# ... work on the task ...
my-assistant track stop
```

### Finding Past Conversations

```bash
# Search for that solution you discussed
my-assistant messages search "authentication middleware"

# Find what you worked on last week
my-assistant messages list my-app --since 2026-01-20

# See Claude's suggestions about a topic
my-assistant messages search "error handling" --type assistant
```

### End of Day

```bash
# See what you accomplished
my-assistant wins

# Output:
# COMPLETED TODAY (5)
#   [todo] #42 Fix authentication bug (my-app)
#   [todo] #45 Review PR for new feature (my-app)
#   [problem] #39 Memory leak in production (api-service)
#   [idea] #33 Implement dark mode (my-app) -> converted to task
#   [todo] #47 Deploy staging environment (my-app)
```

### Weekly Review

```bash
# See your weekly progress
my-assistant wins --week

# Check project health across all projects
my-assistant health
```

## Interactive TUI

Launch the full-featured terminal interface:

```bash
my-assistant tui
```

### TUI Views

The TUI has 4 main views, accessible via number keys:

#### 1. Dashboard View (`1`)

Your daily command center showing everything that needs attention:

```
DASHBOARD - Focus Today

OVERDUE (2)                           DUE TODAY (3)
─────────────────────────────         ─────────────────────────────
> [ ] #42 Fix auth bug @my-app -2d      [ ] #45 Review PR @my-app
  [ ] #38 Update docs @api -1d          [ ] #47 Deploy staging @my-app
                                        [ ] #51 Team sync @general

PROBLEMS (1)
─────────────────────────────
  [ ] #39 Memory leak @api-service
```

- **Navigation:** `j`/`k` or arrows to move, `Tab` to switch sections
- **Actions:** `Space` or `Enter` to toggle item completion
- **Refresh:** `r` to refresh data

#### 2. Weekly View (`2`)

Track your weekly accomplishments and progress:

```
WEEKLY REPORT - This Week

SUMMARY                              BY PROJECT
─────────────────────────────        ─────────────────────────────
Completed: 12  ████████░░ 80%        my-app         ████████░░ 8
Pending:    3                        api-service    ████░░░░░░ 4
                                     general        ██░░░░░░░░ 2

BY TYPE
─────────────────────────────
☐ Todos:     8 completed
✖ Problems:  3 resolved
★ Ideas:     1 converted
```

- **Navigation:** `[` previous week, `]` next week, `0` current week
- **Refresh:** `r` to refresh data

#### 3. Projects View (`3`)

Browse all projects, sessions, and messages in a 3-pane layout:

```
PROJECTS          │ SESSIONS                    │ MESSAGES
──────────────────│─────────────────────────────│────────────────────────────
> my-app          │ Today                       │ Filter: [U] [A] Search: ___
  api-service     │   > 2:30 PM - Fixed auth    │
  general         │     10:15 AM - API refactor │ [U] 2:35 PM How do I fix...
  docs            │ Yesterday                   │ [A] 2:36 PM The issue is...
                  │     4:20 PM - Bug hunting   │ [U] 2:38 PM That worked!
                  │ This Week                   │ [A] 2:39 PM Great! Also...
                  │     Mon - Initial setup     │
```

- **Navigation:** `Tab` to switch panes, `j`/`k` to move within pane
- **Search:** `/` to search messages, `Enter` to apply, `Esc` to cancel
- **Filter:** `u` user messages, `a` assistant messages, `c` compaction
- **Details:** `Enter` on any item to open detail modal
- **Sync:** `s` to sync new sessions from Claude Code

#### 4. Help View (`h`)

Complete keyboard shortcuts reference for all views.

### Project Detail Modal

Press `Enter` on a project to see its details:

```
PROJECT: my-app (1/4)

TODOS (5)                             PROBLEMS (2)
─────────────────────────────         ─────────────────────────────
> [ ] #42 Fix auth bug                  [ ] #39 Memory leak
  [✓] #45 Review PR                     [ ] #52 Slow queries
  [ ] #47 Deploy staging

IDEAS (3)                             RECENT ACTIVITY
─────────────────────────────         ─────────────────────────────
  [ ] #33 Dark mode                   [A] 2:36 PM Fixed the auth...
  [ ] #48 API caching                 [U] 2:30 PM Having issues...
  [ ] #50 Mobile support              [A] 10:20 AM Refactored...
```

- **Navigation:** `Tab` between quadrants, `j`/`k` within quadrant
- **Switch Project:** `[` previous, `]` next project
- **Toggle Done:** `Space` or `Enter` on tasks

### Message Modal

Press `Enter` on a message to view full content:

```
MESSAGE - [USER] my-app > abc123 > 2:35 PM

───────────────────────────────────────────────────────────────────

I'm having an issue with the authentication middleware. When a user
tries to log in with special characters in their password, the
request fails with a 500 error.

Here's the error I'm seeing:
TypeError: Cannot read property 'hash' of undefined
    at AuthMiddleware.verify (/src/middleware/auth.js:42)

I've tried escaping the special characters but that didn't help.

───────────────────────────────────────────────────────────────────
                                               [c] Copy  [Esc] Close
```

- **Scroll:** `j`/`k` line by line, `d`/`u` page by page, `g`/`G` top/bottom
- **Copy:** `c` to copy message to clipboard
- **Close:** `Esc`, `Enter`, or `q`

### TUI Keyboard Reference

| Key | Global | Dashboard | Weekly | Projects | Modals |
|-----|--------|-----------|--------|----------|--------|
| `1` | Dashboard | - | - | - | - |
| `2` | Weekly | - | - | - | - |
| `3` | Projects | - | - | - | - |
| `h` | Help | - | - | - | - |
| `q` | Quit | - | - | - | - |
| `Tab` | - | Switch sections | - | Switch panes | Switch quadrants |
| `j`/`k` | - | Navigate | - | Navigate | Scroll |
| `Space` | - | Toggle done | - | - | Toggle done |
| `Enter` | - | Toggle done | - | Open detail | Close |
| `/` | - | - | - | Search | - |
| `u`/`a`/`c` | - | - | - | Filter | - |
| `[`/`]` | - | - | Prev/Next week | - | Prev/Next project |
| `r` | - | Refresh | Refresh | Refresh | - |
| `s` | - | - | - | Sync | - |
| `c` | - | - | - | - | Copy (message) |
| `Esc` | - | - | - | Cancel search | Close |

## CLI Commands

### Initialization & Health

```bash
my-assistant init              # Full setup: check deps, init db, sync all
my-assistant doctor            # Check system health and configuration
my-assistant reset             # Clear database and resync everything
```

### Task Management

```bash
# Todos
my-assistant todo add <project> "task" [--due DATE] [--recurring daily|weekly|monthly]
my-assistant todo list [project] [--all] [--done]
my-assistant todo done <id> [--note "completion note"]
my-assistant todo priority [project]          # View prioritized queue

# Problems
my-assistant problem add <project> "problem description"
my-assistant problem list [project]

# Ideas
my-assistant idea add <project> "idea description"
my-assistant idea list [project]

# Dependencies
my-assistant todo deps <id> --add <other-id>   # Task blocks another
my-assistant todo deps <id> --remove <other-id>
```

**Due date formats:** `YYYY-MM-DD`, `today`, `tomorrow`, `+N` (days from now)

### Daily Views

```bash
my-assistant briefing          # Morning briefing with priorities
my-assistant focus             # Items due today and overdue
my-assistant focus --week      # Items due this week
my-assistant wins              # Today's completed items
my-assistant wins --week       # This week's wins
my-assistant health [project]  # Project health scores
```

### Time Tracking

```bash
my-assistant track start <id>  # Start tracking time on an item
my-assistant track stop        # Stop current tracking session
my-assistant track status      # Check what you're currently tracking
my-assistant track log <id>    # View time log for an item
```

### Session & Message Search

```bash
# List and search messages
my-assistant messages list [project] [--type user|assistant] [--today] [--since DATE]
my-assistant messages search "query" [--project name] [--regex] [--context 3]

# Project and session management
my-assistant project list
my-assistant project sessions <project>
my-assistant session show <session-id>

# Sync from Claude Code
my-assistant sync              # Incremental sync
my-assistant sync --full       # Full resync
```

### Git Integration

```bash
# Scan commits for item references (auto-completes "fixes #N")
my-assistant git scan <project> [--commits 20] [--dry-run]
```

### Natural Language

```bash
my-assistant ask "add a todo to my-app due tomorrow"
my-assistant ask "show my focus for this week" --execute
```

### Scheduling

```bash
my-assistant schedule list                    # View scheduled tasks
my-assistant schedule set sync hourly         # Change sync frequency
my-assistant schedule set sync --disable      # Pause scheduling
```

## Virtual Projects

Not everything involves Claude Code. Create standalone projects for any work:

```bash
# Create a virtual project (not tied to a filesystem path)
my-assistant project create "Client Meetings" --virtual

# Add items to it
my-assistant todo add "Client Meetings" "Prepare Q1 presentation" --due friday
my-assistant idea add "Client Meetings" "Propose monthly retainer model"
my-assistant problem add "Client Meetings" "Invoice #234 still unpaid"
```

Virtual projects appear in all views alongside your Claude Code projects.

## Data Storage

- **Database:** `~/.assistant/assistant.db` (SQLite)
- **Claude Code data:** Read from `~/.claude/projects/`

The database stores:
- Projects (both from Claude Code and virtual)
- Sessions with metadata and AI-generated summaries
- Messages from Claude Code conversations
- Tasks, problems, and ideas you create
- Time tracking entries
- Sync state for incremental updates

## How It Works

1. **Claude Code** stores session data in `~/.claude/projects/<encoded-path>/`
2. **my-assistant init** sets up the database and syncs everything
3. **Hourly sync** (via cron) keeps your data up to date automatically
4. **Smart extraction** identifies TODOs, problems, and ideas from conversations
5. **AI summaries** are generated for sessions without titles
6. **TUI and CLI** give you multiple ways to interact with your data

## Aliases

Both `my-assistant` and `xo` work as command names:

```bash
xo tui           # Same as my-assistant tui
xo briefing      # Same as my-assistant briefing
xo todo list     # Same as my-assistant todo list
```

## Platform Support

| Platform | Status | Notes |
|----------|--------|-------|
| Linux | Full | Wayland and X11 clipboard support |
| macOS | Full | Intel and Apple Silicon |
| Windows | Partial | No cron scheduling (manual sync only) |

## Development

```bash
bun install          # Install dependencies
bun run dev          # Run in development mode
bun run typecheck    # Type check
bun run build        # Build for production
```

## License

MIT