# Aissist CLI

> Use the aissist CLI tool for personal goal tracking, todo management, daily history logging, context-specific notes, guided reflections, and AI-powered semantic recall. Activate when users mention goals, tasks, todos, progress tracking, journaling, work history, personal assistant, meal planning, fitness tracking, or want to search their past activities and reflections.

- Skill: `diegosouzapw/aissist-cli` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add diegosouzapw/aissist-cli`
- Raw SKILL.md: https://api.skillmd.com/api/skills/diegosouzapw/aissist-cli/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: diegosouzapw (https://skillmd.com/u/diegosouzapw)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/diegosouzapw/aissist-cli

---


# Aissist CLI - Personal AI Assistant

Aissist is a local-first CLI personal assistant that helps users track goals, manage todos, log daily activities, organize context-specific information, and search their data using AI-powered semantic recall.

## When to Use This Skill

Activate this skill when users:
- Want to **set or track goals** ("I want to learn Rust", "track my fitness goals")
- Need **todo/task management** ("add this to my todo list", "what's on my plate today")
- Want to **log their work or activities** ("record what I did today", "log this accomplishment")
- Organize **context-specific information** (work notes, meal plans, fitness logs, project details)
- Need **guided reflection** ("reflect on my week", "journal about today")
- Want to **search past activities** ("what did I work on last month", "find when I learned about X")
- Ask for **action proposals** based on their goals and history

## Quick Start

### Initialization
Before using aissist, storage must be initialized:

```bash
# Local storage (project-specific in ./.aissist/)
aissist init

# Global storage (user-wide in ~/.aissist/)
aissist init --global
```

**When to use which:**
- **Local**: Project-specific goals and todos (e.g., software project tasks)
- **Global**: Personal life goals, general todos, daily reflections

**Interactive Onboarding:**
After successful initialization, aissist will guide you through:
1. Creating your first goal (optional, can be skipped)
2. Adding a todo linked to that goal (optional, can be skipped)

This interactive flow helps you get started quickly. You can press Ctrl+C at any time to skip prompts.

### Hierarchical Configuration (Monorepo Support)

Aissist supports reading data from parent directories while keeping writes isolated to the local directory. Perfect for monorepos and nested projects.

**Initialization with Hierarchy:**
```bash
cd ~/monorepo/packages/api
aissist init

# Aissist detects parent .aissist directories and prompts:
# ✓ Detected .aissist directories in parent paths:
#   • ~/monorepo/.aissist (2 levels up)
#   • ~/.aissist (global)
#
# ? Would you like to include these directories for reading? (Y/n)
```

**Runtime Configuration:**
```bash
# Enable hierarchy after initialization
aissist config hierarchy enable

# Check current status
aissist config hierarchy status

# Disable (sandbox mode)
aissist config hierarchy disable

# View read hierarchy
aissist path --hierarchy
```

**Behavior:**
- **Read**: Access goals, history, and context from parent directories
- **Write**: All changes saved to local directory only (no pollution of parent configs)
- **Precedence**: Local data takes priority when codenames/identifiers conflict

## Core Commands

### Goal Management

```bash
# Add a new goal (AI generates a memorable codename)
aissist goal add "Learn TypeScript fundamentals"

# Add goal with deadline
aissist goal add "Complete project proposal" --deadline "next Friday"

# List all active goals interactively
aissist goal list

# List all active goals in plain text
aissist goal list --plain

# Filter goals by deadline
aissist goal list --deadline 2025-12-01
aissist goal list --deadline "next week"

# Complete a goal
aissist goal complete <codename>

# Set/update deadline
aissist goal deadline <codename> "2024-12-31"
```

**Goal Features:**
- Auto-generated kebab-case codenames (e.g., "learn-typescript-fundamentals")
- Deadline support with natural language parsing
- Interactive management with checkbox UI
- Priority tracking (high/normal/low)
- Post-creation prompt to add linked todos (helps build goal-driven workflows)

### Todo Management

```bash
# Add a todo
aissist todo add "Review PR #123"

# Add todo with priority
aissist todo add "Fix critical bug" --priority high

# Add todo linked to a goal
aissist todo add "Read TypeScript docs" --goal learn-typescript-fundamentals

# List todos interactively
aissist todo list

# Mark todo as done (logs to history automatically)
aissist todo done "Review PR"

# Interactive management (full CRUD)
aissist todo manage
```

**Todo Features:**
- Priority levels (high/normal/low)
- Link to goals for tracking progress
- Interactive checkbox UI
- Automatic history logging when completed

### History Logging

```bash
# Log an entry
aissist history log "Completed code review for authentication feature"

# Log with goal linking
aissist history log "Finished TypeScript tutorial chapter 3" --goal learn-typescript-fundamentals

# Import from GitHub
aissist history log --from github

# Show all history entries
aissist history show

# Show history since specific date
aissist history show --date 2025-01-01
aissist history show --date "last week"
aissist history show --date "last month"
```

**History Features:**
- Daily markdown files (YYYY-MM-DD.md)
- Goal linking for progress tracking
- GitHub import (requires gh CLI)
- Timestamped entries

### Context Management

Organize information by context (work, diet, fitness, projects, etc.):

```bash
# Log context-specific information
aissist context log work "Sprint planning notes: focus on auth module"
aissist context log diet "Meal prep: chicken, rice, vegetables"
aissist context log fitness "Workout: 5k run in 28 minutes"

# Show context entries
aissist context show work --from "this week"

# List all contexts
aissist context list

# Bulk import files
aissist context ingest work ./meeting-notes/
```

### Reflection

Guided reflection with AI-powered prompts:

```bash
# Start interactive reflection
aissist reflect

# Reflect on specific timeframe
aissist reflect --from "this week"
```

### AI-Powered Features

```bash
# Semantic search across all data
aissist recall "what did I learn about TypeScript?"
aissist recall "show my progress on fitness goals"

# Generate action proposals
aissist propose now         # Get 1 immediate action (1-2 hours)
aissist propose             # Daily proposals
aissist propose "this week" # Weekly proposals
```

### Claude Code Plugin Commands

When working within Claude Code, use these slash commands for quick access:

#### `/aissist:log` - AI-Enhanced Quick Logging

Log history entries with AI enhancement and multimodal support. Claude automatically rephrases your input into well-structured entries and links to relevant goals.

```
/aissist:log Fixed auth bug, took 3 hours
```
→ Claude enhances: "Resolved authentication bug in login flow (3 hours)"

**With images/screenshots:**
```
/aissist:log [attach screenshot] Updated dashboard design
```
→ Claude analyzes image: "Updated dashboard: redesigned metrics cards with improved data visualization..."

**Features:**
- AI rephrases rough notes into polished entries
- Preserves exact metrics and time estimates
- Analyzes attached images using vision capabilities
- Automatically links to relevant goals based on content
- Handles multi-line descriptions

**When to use:**
- Quick logging without leaving Claude Code
- Have screenshots or images to log
- Want AI to structure your rough notes
- Need automatic goal linking

#### `/aissist:log-github` - Import GitHub Activity

Import GitHub commits and pull requests as history entries with semantic summarization.

```
/aissist:log-github today
/aissist:log-github "this week"
/aissist:log-github "last month"
```

**Features:**
- Fetches commits and PRs from specified timeframe
- Semantically groups related changes
- Auto-links to relevant goals
- Requires GitHub CLI (`gh`) authentication

**When to use:**
- Bulk import of recent development work
- End of day/week to catch all GitHub activity
- Want automated activity summarization

#### `/aissist:recall` - Semantic Search

Search your history, goals, and reflections using natural language queries.

```
/aissist:recall "what did I learn about TypeScript last month?"
/aissist:recall "show my fitness progress"
```

#### `/aissist:report` - Generate Reports

Create accomplishment reports from your history for various purposes.

```
/aissist:report "this week" --purpose standup
/aissist:report "last month" --purpose performance-review
```

**Command Comparison:**

| Command | Purpose | Input | Output |
|---------|---------|-------|--------|
| `/aissist:log` | Quick history logging | Text + images | AI-enhanced entry |
| `/aissist:log-github` | GitHub import | Timeframe | Summarized commits/PRs |
| `/aissist:recall` | Search history | Natural language query | Relevant entries |
| `/aissist:report` | Generate reports | Timeframe + purpose | Formatted report |

## Command Construction Guidelines

1. **Always check if storage is initialized** - If user is new to aissist, suggest `aissist init` first
2. **Use goal codenames for linking** - When linking to goals, use the kebab-case codename
3. **Natural language deadlines** - Aissist parses "next Friday", "end of month", "2024-12-31"
4. **Interactive when appropriate** - Suggest `list` or `manage` commands for better UX over plain text
5. **Link related data** - When logging history or todos, link to relevant goals using `--goal`

## Progressive Disclosure

For detailed information, reference these supporting files:
- **command-reference.md** - Complete command documentation with all options
- **workflow-examples.md** - Multi-step workflows and usage patterns
- **storage-model.md** - Storage concepts and file organization

## Common Patterns

**Morning Routine:**
```bash
aissist todo list  # Review today's tasks
```

**Evening Routine:**
```bash
aissist history log "Completed X, Y, and Z today"
aissist todo done "task description"  # Marks done and logs to history
```

**Goal Progress:**
```bash
aissist goal list  # Review goals
aissist history show --from "this week"  # See recent progress
aissist recall "progress on <goal>"  # AI-powered progress review
```

**Weekly Planning:**

```bash
aissist reflect --from "this week"  # Reflect on the week
aissist propose  # Get AI-generated action proposals
```


## Error Handling

If commands fail:
- Check if storage is initialized: `aissist path` shows current storage location
- Verify goal codenames with: `aissist goal list --plain`
- For recall/propose, ensure Claude API key is configured: `claude login`

## Tips for Effective Use

1. **Consistent logging** - Encourage users to log daily for better recall
2. **Goal linking** - Always link todos and history to goals for progress tracking
3. **Use contexts** - Separate work, personal, fitness, etc. for better organization
4. **Weekly reflection** - Suggest regular reflection for self-awareness
5. **Leverage recall** - Use semantic search instead of manually browsing files