PARA Agent

A file organization CLI I built because my Documents folder was a disaster. Based on Tiago Forte's PARA Method.

Projects, Areas, Resources, Archives — organize your digital life by actionability, not category.

<!-- Badges -->

---

How It Works

flowchart LR
    subgraph INPUT
        A[Messy Files]
    end

    subgraph PARA_AGENT["PARA Agent"]
        B[Scan] --> C[Classify]
        C --> D[Move]
        D --> E[Trace]
    end

    subgraph OUTPUT
        F[Projects]
        G[Areas]
        H[Resources]
        I[Archives]
    end

    A --> B
    E --> F
    E --> G
    E --> H
    E --> I

The flow:

1. Scan — Analyze what you've got
2. Classify — Get smart suggestions for each item
3. Move — Approve and organize (always asks first)
4. Trace — Every action logged, fully reversible

---

Features

• Interactive classification — Guided questions that sort files into the right bucket
• Permission-first — Always asks before moving, renaming, or archiving
• Full observability — Every action traced and reversible
• Cross-platform — Works on macOS, Linux, and Windows
• MCP server included — Plug it into Claude Code and let AI organize for you

Quick Start

# Install globally
npm install -g para-agent

# Initialize PARA in your Documents folder
cd ~/Documents
para init

# Scan and see what you have
para scan

# Get classification suggestions
para classify --all

# View your dashboard
para status

The PARA Method

PARA organizes information by actionability — how soon you'll need it:

| Category | Definition | Has Deadline? | Example | |----------|------------|---------------|---------| | Projects | Active work with a goal | Yes | Website Redesign | | Areas | Ongoing responsibilities | No | FINANCES | | Resources | Reference material | No | design-inspiration | | Archives | Inactive/completed | N/A | Archive 2024-01-15 |

Decision Tree

Not sure where something belongs? Follow this:

flowchart TD
    A[New Item] --> B{Has specific<br/>goal + deadline?}
    B -->|Yes| C[PROJECT]
    B -->|No| D{Ongoing<br/>responsibility?}
    D -->|Yes| E[AREA]
    D -->|No| F{Useful for<br/>future reference?}
    F -->|Yes| G[RESOURCE]
    F -->|No| H{Still need it?}
    H -->|Yes| I[ARCHIVE]
    H -->|No| J[DELETE]

    style C fill:#22c55e,color:#fff
    style E fill:#3b82f6,color:#fff
    style G fill:#a855f7,color:#fff
    style I fill:#6b7280,color:#fff
    style J fill:#ef4444,color:#fff

Folder Structure

Documents/
├── 0 Inbox/           # Temporary landing zone
├── 1 Projects/        # Active, time-bound work
├── 2 Areas/           # Ongoing responsibilities
├── 3 Resources/       # Reference materials
├── 4 Archives/        # Completed/inactive items
└── .para/             # Config and traces
    ├── config.yaml
    └── traces/

Commands

para init

Initialize PARA structure in a directory.

para init                    # Current directory
para init --path ~/Documents # Specific path
para init --no-archive       # Don't archive existing files

What it does:

1. Creates the 5 PARA folders (0 Inbox through 4 Archives)
2. Optionally archives existing loose files
3. Sets up .para/ config directory
4. Asks your permission preference (strict/balanced/autonomous)

para scan

Analyze your directory and see what's where.

para scan                    # Scan current directory
para scan --depth 3          # Scan deeper into folders

Output:

┌─────────────────────────────────────────────┐
│  PARA AGENT - SCAN RESULTS                  │
├─────────────────────────────────────────────┤
│  Category          Items    Status          │
│  0 Inbox           3        ok              │
│  1 Projects        5        ok              │
│  2 Areas           2        ok              │
│  3 Resources       8        ok              │
│  4 Archives        12       ok              │
│  Uncategorized     4        needs sorting   │
└─────────────────────────────────────────────┘

para classify

Get intelligent suggestions for where files belong.

para classify my-file.pdf    # Classify specific item
para classify --all          # Classify all uncategorized items

Interactive flow:

Classifying: quarterly-report.docx

Suggested: 1 Projects
Reason: Name suggests work in progress

? Classify "quarterly-report.docx" as 1 Projects?
  > Accept (1 Projects)
    Choose different category
    Skip this item

para move

Move items to a PARA category.

para move my-file.pdf                    # Interactive category selection
para move my-file.pdf --category projects
para move my-file.pdf -c areas -n "NEW NAME"

Features:

• Shows preview before moving
• Applies naming conventions automatically
• Logs action for undo

para status

View your PARA dashboard.

para status

Shows:

• Item counts per category
• Last modified dates
• Undo stack status
• Health suggestions

para trace

View action history for debugging and review.

para trace                   # Recent actions
para trace --item my-file    # History of specific item
para trace --export          # Export all traces to JSON

para undo

Reverse the last action.

para undo

Shows what'll be undone and asks for confirmation.

para archive

Archive items or declare "digital bankruptcy."

para archive file1.txt file2.pdf    # Archive specific items
para archive --bankruptcy            # Archive EVERYTHING (clean slate)

Bankruptcy is for when things get overwhelming. It:

1. Moves all loose files to a dated archive folder
2. Creates a manifest for easy searching later
3. Gives you a fresh start

Configuration

Config lives in .para/config.yaml:

para_agent:
  version: "0.1.0"
  root: "/Users/you/Documents"
  initialized_at: "2024-01-15T10:30:00Z"

structure:
  inbox: "0 Inbox"
  projects: "1 Projects"
  areas: "2 Areas"
  resources: "3 Resources"
  archives: "4 Archives"

naming:
  projects: emoji_prefix    # Project Name
  areas: all_caps           # FINANCES
  resources: lowercase      # design-inspiration

permissions:
  mode: balanced            # strict | balanced | autonomous

observability:
  trace_level: normal       # minimal | normal | verbose

Permission Modes

| Mode | Behavior | |------|----------| | strict | Ask before every single action | | balanced | Ask for moves/archives, auto-suggest classifications | | autonomous | Auto-organize with logging (review traces later) |

Observability

Every action gets logged to .para/traces/YYYY-MM-DD.jsonl:

{
  "trace_id": "abc-123",
  "timestamp": "2024-01-15T10:30:00Z",
  "session_id": "session-456",
  "event_type": "MOVE",
  "action": "MOVE_ITEM",
  "source": "quarterly-report.docx",
  "destination": "1 Projects/Q1 Report/quarterly-report.docx",
  "category": "projects",
  "permission": { "required": true, "granted": true },
  "reversible": true,
  "status": "success"
}

Use traces to:

• Debug what happened
• Review agent decisions
• Audit file movements
• Undo mistakes

Examples

Fresh Start

# You've got a messy Documents folder
cd ~/Documents
para init

# Archive existing files automatically
? Proceed with initialization? Yes

# PARA structure created
# 47 existing items archived to 4 Archives/Archive 2024-01-15

Weekly Review

# Check what needs attention
para scan

# Classify items in inbox
para classify --all

# Move items as suggested
# (interactive prompts guide you)

# Check status
para status

Quick Sort

# Got a new file, need to put it somewhere
para classify downloads/important-doc.pdf

# Suggested: Areas (WORK)
# Accept or choose different

para move downloads/important-doc.pdf -c areas
# Moved to: 2 Areas/WORK/important-doc.pdf

Recovery

# Made a mistake?
para undo

# Last action: move
#   From: 2 Areas/WORK/important-doc.pdf
#   To: downloads/important-doc.pdf
# ? Undo? Yes
# Moved back to downloads/

MCP Server (Claude Code Integration)

PARA Agent includes an MCP server so Claude can organize your files directly.

Setup:

1. Clone and build:

git clone https://github.com/bennjph/para-agent.git
cd para-agent
npm install
npm run build

2. Add to your Claude Code MCP config (~/.claude.json or project settings):

{
  "mcpServers": {
    "para-agent": {
      "command": "node",
      "args": ["/path/to/para-agent/dist/mcp/server.js"],
      "env": {
        "PARA_ROOT": "/Users/you/Documents"
      }
    }
  }
}

3. Restart Claude Code. These tools become available:

| Tool | Description | |------|-------------| | para_status | Check PARA health and item counts | | para_scan | Scan directory and categorize items | | para_classify | Get suggestions for where items belong | | para_classify_inbox | Classify all inbox items at once | | para_move | Move items to PARA categories | | para_init | Initialize PARA structure | | para_archive | Archive items with manifest | | para_create_project | Create new project folder | | para_create_area | Create new area folder |

Example conversation:

You: "Scan my Documents and tell me what needs organizing"
Claude: [calls para_scan] "You have 5 items in your inbox..."

You: "Move that report to Projects"
Claude: [calls para_move] "Done! Moved to 1 Projects/Q1 Report/"

Programmatic Usage

import { scanDirectory, classifyItem, moveItem } from 'para-agent';

const result = scanDirectory('/path/to/docs');
const classification = classifyItem(result.items[0]);
console.log(classification.suggestedCategory);

Philosophy

1. Permission-first — Your files, your decisions. We always ask.
2. Radical transparency — Every action is logged and reversible.
3. Fail gracefully — Works even when you're not perfect.
4. Minimal friction — Organize just-in-time, not just-in-case.

Known Limitations

• No test suite yet. The project has vitest wired up but zero coverage. Adding tests is a great first contribution — see CONTRIBUTING.md.
• Large modules. The CLI and MCP server are monolithic files. Refactoring them into smaller units is on the roadmap.

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines.

git clone https://github.com/bennjph/para-agent.git
cd para-agent
npm install
npm run build
node dist/cli/index.js status

Learn More About PARA

This tool implements the PARA Method created by Tiago Forte.

• The PARA Method Explained — Free comprehensive guide
• Forte Labs — Tiago Forte's official site
• Building a Second Brain — Related methodology

This is an independent open-source project, not affiliated with or endorsed by Forte Labs.

---

License

MIT License — see LICENSE for details.

Built by Benison Joseph.