Deepthink

Step 1: Create Data Directory

mkdir -p ~/.claude/deepthink-data/{topics,research,sessions}
echo '{"topics":[]}' > ~/.claude/deepthink-data/index.json

Step 2: Check xurl (X/Twitter CLI)

which xurl || echo "NOT_FOUND"

• If found → ✅ xurl found
• If not found → guide user:

  ⚠️ xurl not found. xurl is needed for X/Twitter research.
  
  Install options:
  1. Homebrew (macOS): brew install xurl
  2. Manual: https://github.com/xurl-cli/xurl
  
  After install, configure OAuth:
    xurl auth login --app deepthink
  
  You can skip this for now — Stage 2 will work with Perplexity + RSS only.
  

Step 3: Check Perplexity API Key

test -f ~/.claude/deepthink-data/.env && grep -q PERPLEXITY_API_KEY ~/.claude/deepthink-data/.env && echo "FOUND" || echo "NOT_FOUND"

• If found → ✅ Perplexity API key configured
• If not found → ask user:

  🔑 Perplexity API key needed for deep research.
  
  1. Get your API key at: https://www.perplexity.ai/settings/api
  2. Paste it here (I'll save it securely):
  

  Save to ~/.claude/deepthink-data/.env:

  PERPLEXITY_API_KEY={user_input}
  

Step 4: Verify RSS (no config needed)

RSS uses WebFetch — no API key required. Just confirm:

✅ RSS feeds: 11 curated AI sources ready (see sources.md)

Step 5: Setup Complete

🎉 DeepThink setup complete!

✅ Data directory: ~/.claude/deepthink-data/
{✅|⚠️} xurl (X/Twitter): {status}
✅ Perplexity API: configured
✅ RSS feeds: 11 sources ready

Get started:
  /deepthink new: {your topic}    — Start thinking about something
  /deepthink                      — See all commands

Three-Stage Workflow

User records topic → Stage 1: Understanding → Stage 2: Deep Research → Stage 3: Guided Thinking
                                                          ↑                      ↓
                                                          └──── Loop back ───────┘

Stage 1: Understanding Alignment

Trigger: user says new: {topic} or I want to think deeply about {topic}

Flow:

1. Generate topic_id (UUID v4), create initial topic record
2. One round of questions — directly ask user's motivation and background (see references/stage1_understanding.md)
3. Based on answers, Agent summarizes understanding, outputs structured summary
4. User confirms "you got it right" → save complete topic record, stage → research
5. Prompt user to run research

Key principle: One round of questions, no multi-round interview. Focus on "why do you want to research this".

Stage 2: Deep Research

Trigger: user says research {topic} or scheduled trigger

Flow:

1. Read topic record, get core_question, tags, preferred_angle
2. Generate search strategy (3 xurl search terms + 2-round Perplexity queries + RSS source matching)
3. Three-source collection: X/Twitter (xurl CLI) + Perplexity API (curl) + RSS (WebFetch)
4. Synthesize research article (Markdown), generate 3-5 thinking questions
5. Persist: write to research/{research_id}.json, update topic and index

Tool chain (non-substitutable, WebSearch banned as primary source):

• X/Twitter: must use xurl search "..." -n 10 --app deepthink (Bash execution, xurl at $(which xurl))
• Perplexity: must use curl https://api.perplexity.ai/chat/completions (API key from ~/.claude/deepthink-data/.env), must do 2 rounds
• RSS: must use WebFetch to pull RSS feed URLs from sources.md → title scan → full text extraction of relevant articles

Execution discipline: Output search strategy first (checkpoint), then three-source collection, self-check data sources before synthesis. See references/stage2_research.md.

Stage 3: Guided Thinking

Trigger: user says chat {topic} or continue {topic}

Role: Thinking coach. Ask questions, follow up, provide counter-perspectives. Can share own opinions as supplementary dimensions, but never make judgments for the user.

Flow:

1. Read latest research article + all historical thinking sessions
2. First session: Show research article's thinking questions, let user choose interest anchor
3. Subsequent sessions: Start from previous session's open_questions, maintain continuity
4. Question types cycle: exploratory → deep-dive → challenge → connecting, 1 question per turn, no consecutive challenges
5. User ends manually → output session summary + thinking timeline
6. Persist to sessions/{session_id}.json, update topic record

Core discipline: No more than 3 paragraphs per response. You're guiding, not lecturing.

See references/stage3_thinking.md.

Command Routing

When user invokes /deepthink, route by argument:

Data Layer

Storage Location

All data persisted to ~/.claude/deepthink-data/:

~/.claude/deepthink-data/
├── .env                # API keys (PERPLEXITY_API_KEY)
├── index.json          # Topic index (all topic IDs + basic info)
├── topics/             # Full topic records
│   └── {topic_id}.json
├── research/           # Research records
│   └── {research_id}.json
└── sessions/           # Thinking session records
    └── {session_id}.json

Data Operations

Read index:

cat ~/.claude/deepthink-data/index.json

Create/update topic:

1. Read index.json with Read tool
2. Write topics/{topic_id}.json with Write tool
3. Update index.json with Edit tool

Find topic (fuzzy match by name): Search the topics array in index.json for titles containing user's keywords.

Data Models

Topic

{
  "topic_id": "uuid-v4",
  "title": "Short title",
  "core_question": "Agent-distilled core question",
  "user_context": "User's existing knowledge and background",
  "thinking_goal": "Purpose of thinking",
  "preferred_angle": "Preferred entry angle",
  "stage": "understanding | research | thinking | archived",
  "priority": "high | medium | low",
  "created_at": "ISO timestamp",
  "last_interaction": "ISO timestamp",
  "research_history": [],
  "thinking_sessions": [],
  "tags": []
}

Research Record — Stage 2

{
  "research_id": "uuid-v4",
  "topic_id": "Associated topic ID",
  "researched_at": "ISO timestamp",
  "article_markdown": "Full research article",
  "sources": { "x_twitter": [], "web_search": [], "rss_feeds": [] },
  "thinking_questions": [],
  "source_stats": { "x_count": 0, "search_count": 0, "rss_count": 0 },
  "execution_log": { "xurl_calls": 0, "perplexity_rounds": 0, "rss_feeds_fetched": 0, "errors": [] }
}

Thinking Session — Stage 3

{
  "session_id": "uuid-v4",
  "topic_id": "Associated topic ID",
  "session_number": 1,
  "date": "ISO timestamp",
  "key_insights": [],
  "open_questions": [],
  "belief_changes": "",
  "thinking_evolution": "What this session advanced",
  "follow_up_needed": false,
  "next_research_direction": "",
  "conversation_summary": "3-5 sentence summary of conversation"
}

Source Configuration

Source list in sources.md. Agent reads this file during Stage 2 to match sources by topic domain.

Execution Checklist

On every invocation:

1. Check if ~/.claude/deepthink-data/ exists — if not, run setup flow
2. Read ~/.claude/deepthink-data/index.json
3. Parse user command, route to matching action
4. Load corresponding stage's references file
5. After execution, ensure all data changes are written to disk
6. Output clear status feedback to user