Research Assistant
Agent

Build an AI agent that organizes your research, collects notes from multiple sources, and generates structured markdown reports. Built with OpenCode in under 25 minutes.

Start Building Setup Guide First
Need to set up OpenCode first?

This guide assumes you have OpenCode and a free model provider configured. If you haven't set that up yet:

  1. Install OpenCode: curl -fsSL https://opencode.ai/install | bash
  2. Get a free API key from OpenRouter (no credit card needed)
  3. Or follow the full setup guide for detailed steps

What You'll Build

By the end of this guide, you'll have a command-line research assistant that can:

  • Collect notes from text you paste in -- quotes, facts, URLs, observations
  • Organize by topic with tags and categories you define
  • Generate structured reports as markdown files with sections, key findings, and source references
  • Track sources with proper attribution (URL, author, date accessed)
  • Create summaries at different lengths -- one-liner, paragraph, or full brief

This is a note-collection and report-generation tool. You feed it information you've gathered, and it organizes and formats it into a structured output. Think of it as a local, private research notebook that generates polished reports.

Great for students and professionals
Use this for class papers, market research, competitive analysis, or any project where you need to collect information from multiple sources and produce a structured report. All data stays local on your machine.
1

Create Your Project

Set up a project folder with directories for notes and reports.

mkdir -p ~/projects/research-agent/{notes,reports}
cd ~/projects/research-agent
mkdir -p ~/projects/research-agent/{notes,reports}
cd ~/projects/research-agent

Create the AGENTS.md context file:

# Research Assistant Agent

## Project Type
Python CLI application

## Description
A command-line research assistant that collects notes, organizes them by
topic and tags, tracks sources, and generates structured markdown reports.

## Tech Stack
- Python 3.8+ (standard library only)
- JSON for note storage (notes/notes.json)
- Markdown for report output (reports/ directory)

## Conventions
- Use type hints
- Notes are stored as JSON objects with: content, source, tags, date, topic
- Reports follow a standard structure: Title, Summary, Key Findings,
  Detailed Notes, Sources, Methodology
- Tags are lowercase, hyphenated (e.g., "market-size", "competitor-analysis")
- Each research project gets its own topic namespace

Save as AGENTS.md and start OpenCode:

opencode
2

Build the Research Assistant

Give OpenCode the task and it will generate the complete research tool.

Type this into OpenCode:

Create a Python script called researcher.py with an interactive menu:

1. New research topic (creates a named topic/project)
2. Add note (paste text, provide source URL/name, add tags)
3. View notes (filter by topic, tag, or keyword search)
4. Generate report (pick a topic, outputs structured markdown)
5. List topics (show all research topics with note counts)
6. Export (save report as .md file in reports/ directory)
7. Quit

Notes should be stored in notes/notes.json with fields:
id, topic, content, source_name, source_url, tags[], date_added

Reports should include:
- Title and date
- Executive summary (2-3 sentences)
- Key findings (bullet points)
- Detailed notes organized by tag
- Sources list with URLs
- Word count and note count stats

Make the report generation smart: group notes by tag, identify
the most common themes, and put the most-cited sources first.

OpenCode will generate the complete script. The output typically includes:

  • A Note dataclass and a ResearchProject manager class
  • JSON-based persistence for all notes with full-text search
  • A report generator that structures notes into proper sections
  • Tag-based filtering and theme detection
  • Markdown export with clean formatting
3

Run and Iterate

Test with a real research topic and refine the report output.

Run your research assistant:

python3 researcher.py

Try creating a topic and adding a few notes. Here's a test workflow:

================================
  Research Assistant
================================

1. New research topic
2. Add note
3. View notes
4. Generate report
5. List topics
6. Export report
7. Quit

Choice: 1
Topic name: ai-code-editors

Choice: 2
Topic: ai-code-editors
Note content: OpenCode is an open-source terminal AI coding agent that
supports multiple LLM providers through OpenRouter. It reads AGENTS.md
files for project context.
Source name: OpenCode docs
Source URL: https://opencode.ai
Tags (comma-separated): tools, open-source, terminal

Note added! (ID: 1)

Choice: 4
Topic: ai-code-editors

--- Generating report... ---

# AI Code Editors - Research Report
Generated: 2026-04-03

## Executive Summary
This research covers AI-powered code editors with 1 note across
1 source. Primary themes: tools, open-source, terminal.

## Key Findings
- OpenCode provides terminal-based AI coding with multi-provider support
...

Iterate with OpenCode

Go back to OpenCode to add more features:

# Better reports
Add a "confidence level" field to each note (high, medium, low)
and include a methodology section in reports that notes how many
sources were high-confidence vs low.

# Import from clipboard
Add an option to quickly add a note by pasting from clipboard
with auto-detection of URLs in the pasted text.

# Comparison tables
When generating a report, detect if notes contain comparisons
between items (e.g., "Tool A vs Tool B") and auto-generate a
comparison table in the markdown output.
Track your project with git
Initialize a repo with git init and push to GitHub. Your research data (the JSON files) can be version controlled too, so you have a full history of how your research evolved.

Example Prompts to Try

Once the basic researcher works, extend it:

# Citation formatting
Add citation format options: APA, MLA, Chicago. When generating
a report, format the Sources section in the chosen style.

# Timeline view
Add a timeline feature that shows when each note was added,
helping visualize the research progression over time.

# Merge topics
Add the ability to merge two research topics into one, combining
all notes and deduplicating sources.

# Quick capture
Add a command-line argument mode so I can add notes without
entering the interactive menu:
python3 researcher.py add "ai-tools" "Note text" --source "URL"

# PDF-ready output
Generate reports with proper heading hierarchy and formatting
that converts cleanly to PDF using pandoc:
pandoc reports/my-report.md -o reports/my-report.pdf

What's Next?

You've built a working research assistant. Here are your options:

  • Build a web interface: Wrap it in Flask and deploy to Cloudflare Pages for a browser-based research tool.
  • Publish your reports: Push generated markdown reports to GitHub Pages for free hosting.
  • Add analytics: Track which reports get the most views with Umami.
  • Try another agent: Same setup, different task:

Ready for the Next Agent?

The pattern is always the same: create a folder, write AGENTS.md, give OpenCode the task. The only thing that changes is the prompt.

Build Finance Agent All Guides