Chonkie DeepResearch

Chonkie DeepResearch

Run deep research queries from your agent and get comprehensive reports with citations.

Setup

Before using, check if chdr is installed (which chdr). If not:

1. Install: cargo install chdr - If cargo isn't available, install Rust first: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh 2. Authenticate: chdr auth login (opens browser to get an API key) - Or set CHONKIE_API_KEY environment variable - Get a key at https://labs.chonkie.ai/settings/api-keys

Usage

IMPORTANT: Research takes 2-10 minutes. Always spawn a sub-agent to avoid blocking the main thread.

Running research (recommended: sub-agent)

Use sessions_spawn to run the research in a sub-agent. The sub-agent handles the long-running query and announces the result when done, so your main agent stays responsive.

{
  "tool": "sessions_spawn",
  "task": "Run chdr research and save results. Steps:\n1. Run: chdr research --type report --no-stream --json \"\" > /tmp/chdr-research-.json\n2. Extract ID and title: python3 -c \"import json; d=json.load(open('/tmp/chdr-research-.json')); print(d['id']); print(d.get('title','Untitled'))\"\n3. Extract body: python3 -c \"import json; d=json.load(open('/tmp/chdr-research-.json')); print(d.get('content',{}).get('body',''))\" > /tmp/chdr-research-.md\n4. Report back the title, ID, and URL: https://labs.chonkie.ai/research/{id}"
}

Replace with the research query and with $(date +%s).

Monitoring research status

Do NOT poll continuously for status. Instead, set up a cron job to check periodically (every 2-3 minutes):

# Add a cron entry to check research status every 2 minutes
The cron should run: chdr view  --json | python3 -c "import json,sys; d=json.load(sys.stdin); s=d.get('status','unknown'); print(s)"
and notify you when status is 'completed' or 'failed'

Or simply wait for the sub-agent to announce completion — it will report back automatically when the research finishes. The sub-agent approach is preferred over cron for one-off research queries.

After research completes

When the sub-agent announces completion:

1. The web URL is: https://labs.chonkie.ai/research/{id} 2. The full report is saved at /tmp/chdr-research-.md 3. Read only the first 100 lines for a summary — NEVER load the entire file 4. Tell the user you can answer questions about the report

Answering follow-up questions

Fallback: running without sub-agent

If sub-agents are unavailable, run the research command directly but warn the user it will block for several minutes:

chdr research --type report --no-stream --json "" > /tmp/chdr-research.json

Other commands

chdr ls                    # List recent research
chdr ls --limit 20         # List more
chdr view              # View a report (supports partial ID prefix)
chdr open              # Open in browser
chdr delete            # Delete a report

All commands that take an ID support prefix matching — chdr view 3a6b works if unambiguous.

IMPORTANT: Research takes 2-10 minutes. Always spawn a sub-agent to avoid blocking the main thread.

Running research (recommended: sub-agent)

Use sessions_spawn to run the research in a sub-agent. The sub-agent handles the long-running query and announces the result when done, so your main agent stays responsive.

{
  "tool": "sessions_spawn",
  "task": "Run chdr research and save results. Steps:\n1. Run: chdr research --type report --no-stream --json \"\" > /tmp/chdr-research-.json\n2. Extract ID and title: python3 -c \"import json; d=json.load(open('/tmp/chdr-research-.json')); print(d['id']); print(d.get('title','Untitled'))\"\n3. Extract body: python3 -c \"import json; d=json.load(open('/tmp/chdr-research-.json')); print(d.get('content',{}).get('body',''))\" > /tmp/chdr-research-.md\n4. Report back the title, ID, and URL: https://labs.chonkie.ai/research/{id}"
}

Replace with the research query and with $(date +%s).

Monitoring research status

Do NOT poll continuously for status. Instead, set up a cron job to check periodically (every 2-3 minutes):

# Add a cron entry to check research status every 2 minutes
The cron should run: chdr view  --json | python3 -c "import json,sys; d=json.load(sys.stdin); s=d.get('status','unknown'); print(s)"
and notify you when status is 'completed' or 'failed'

Or simply wait for the sub-agent to announce completion — it will report back automatically when the research finishes. The sub-agent approach is preferred over cron for one-off research queries.

After research completes

When the sub-agent announces completion:

1. The web URL is: https://labs.chonkie.ai/research/{id} 2. The full report is saved at /tmp/chdr-research-.md 3. Read only the first 100 lines for a summary — NEVER load the entire file 4. Tell the user you can answer questions about the report

Answering follow-up questions

Fallback: running without sub-agent

If sub-agents are unavailable, run the research command directly but warn the user it will block for several minutes:

chdr research --type report --no-stream --json "" > /tmp/chdr-research.json

Other commands

chdr ls                    # List recent research
chdr ls --limit 20         # List more
chdr view              # View a report (supports partial ID prefix)
chdr open              # Open in browser
chdr delete            # Delete a report

All commands that take an ID support prefix matching — chdr view 3a6b works if unambiguous.

Before using, check if chdr is installed (which chdr). If not:

1. Install: cargo install chdr - If cargo isn't available, install Rust first: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh 2. Authenticate: chdr auth login (opens browser to get an API key) - Or set CHONKIE_API_KEY environment variable - Get a key at https://labs.chonkie.ai/settings/api-keys