{"id":44155462,"url":"https://github.com/24601/agent-deep-research","last_synced_at":"2026-02-25T06:47:47.862Z","repository":{"id":337352522,"uuid":"1153201241","full_name":"24601/agent-deep-research","owner":"24601","description":"Deep research (CLI and agent skill) via the Gemini Interactions API. Automatic RAG grounding from local files (optional), cost estimation (--dry-run), adaptive polling, structured output, and agent onboarding. No Gemini CLI dependency. Universal AI agent skill for Claude Code, Amp, Codex, Clawdbot, and 30+ agents.","archived":false,"fork":false,"pushed_at":"2026-02-19T23:34:40.000Z","size":8874,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-20T03:28:57.671Z","etag":null,"topics":["agent-skill","ai-agent","ai-agent-skill","autonomous-agent","claude-code","claude-code-skill","clawdbot","clawdbot-skill","clawdhub","coding-agent","deep-research","deep-research-agent","gemini","gemini-api","gemini-interactions-api","google-gemini","openclaw-skill","python","rag","uv"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/24601.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-09T02:54:36.000Z","updated_at":"2026-02-19T23:34:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/24601/agent-deep-research","commit_stats":null,"previous_names":["24601/agent-deep-research"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/24601/agent-deep-research","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/24601%2Fagent-deep-research","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/24601%2Fagent-deep-research/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/24601%2Fagent-deep-research/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/24601%2Fagent-deep-research/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/24601","download_url":"https://codeload.github.com/24601/agent-deep-research/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/24601%2Fagent-deep-research/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29694200,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T18:18:25.093Z","status":"ssl_error","status_checked_at":"2026-02-21T18:18:22.435Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skill","ai-agent","ai-agent-skill","autonomous-agent","claude-code","claude-code-skill","clawdbot","clawdbot-skill","clawdhub","coding-agent","deep-research","deep-research-agent","gemini","gemini-api","gemini-interactions-api","google-gemini","openclaw-skill","python","rag","uv"],"created_at":"2026-02-09T05:20:22.128Z","updated_at":"2026-02-25T06:47:47.855Z","avatar_url":"https://github.com/24601.png","language":"Python","funding_links":[],"categories":["🔬 Research / Academic"],"sub_categories":["Reading \u0026 Synthesis"],"readme":"# agent-deep-research\n\n[![CI](https://github.com/24601/agent-deep-research/actions/workflows/ci.yml/badge.svg)](https://github.com/24601/agent-deep-research/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Latest Release](https://img.shields.io/github/v/release/24601/agent-deep-research)](https://github.com/24601/agent-deep-research/releases)\n\nDeep research and RAG-grounded file search powered by the Google Gemini Interactions API. A universal AI agent skill that works with Claude Code, Amp, Codex, OpenCode, Cursor, Gemini CLI, and [30+ other agents](https://skills.sh). No dependency on the Gemini CLI -- uses the `google-genai` Python SDK directly via `uv run`.\n\n## Installation\n\n```bash\nnpx skills add 24601/agent-deep-research\n```\n\n### Agent-specific installation\n\n```bash\n# Claude Code\nnpx skills add 24601/agent-deep-research -a claude-code -g -y\n\n# Amp\nnpx skills add 24601/agent-deep-research -a amp -g -y\n\n# Codex\nnpx skills add 24601/agent-deep-research -a codex -g -y\n\n# Gemini CLI\nnpx skills add 24601/agent-deep-research -a gemini-cli -g -y\n\n# OpenCode\nnpx skills add 24601/agent-deep-research -a opencode -g -y\n\n# Pi (badlogic/pi-mono)\nnpx skills add 24601/agent-deep-research -a pi -g -y\n\n# OpenClaw / Clawdbot\nnpx skills add 24601/agent-deep-research -a openclaw -g -y\n```\n\n### Pi agent (manual install)\n\nIf you prefer manual installation for [Pi](https://github.com/badlogic/pi-mono):\n\n```bash\n# Clone to Pi's global skills directory\ngit clone https://github.com/24601/agent-deep-research.git ~/.pi/agent/skills/deep-research\n\n# Or add to Pi settings.json to load from an existing directory\n# ~/.pi/settings.json:\n# { \"skills\": [\"~/.agents/skills\"] }\n```\n\nThen use `/skill:deep-research` in Pi, or let Pi auto-detect it from the description.\n\n### ClawHub (OpenClaw registry)\n\n```bash\nnpx clawhub install agent-deep-research\n```\n\nOr browse at [clawhub.ai/skills/agent-deep-research](https://clawhub.ai/skills/agent-deep-research).\n\n## Prerequisites\n\n- A Google API key (see [Configuration](#configuration))\n- [uv](https://docs.astral.sh/uv/) (see [install docs](https://docs.astral.sh/uv/getting-started/installation/))\n\n## Configuration\n\nSet one of the following environment variables (checked in order of priority):\n\n| Variable | Description |\n|----------|-------------|\n| `GEMINI_DEEP_RESEARCH_API_KEY` | Dedicated key for this skill (highest priority) |\n| `GOOGLE_API_KEY` | Standard Google AI key |\n| `GEMINI_API_KEY` | Gemini-specific key |\n\nOptional model configuration:\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `GEMINI_DEEP_RESEARCH_MODEL` | Model for file search queries | `gemini-3.1-pro-preview` |\n| `GEMINI_MODEL` | Fallback model name | `gemini-3.1-pro-preview` |\n| `GEMINI_DEEP_RESEARCH_AGENT` | Deep research agent identifier | `deep-research-pro-preview-12-2025` |\n\n## Quick Start\n\n```bash\n# Run a deep research query (blocks until complete, saves to file)\nuv run scripts/research.py \"What are the latest advances in quantum computing?\" --output report.md\n\n# Non-blocking: start and check later\nuv run scripts/research.py start \"Analyze the security landscape\"\nuv run scripts/research.py status \u003cinteraction-id\u003e\nuv run scripts/research.py report \u003cinteraction-id\u003e --output report.md\n\n# Structured output for agent integration\nuv run scripts/research.py start \"Deep analysis\" --output-dir ./research-output\n\n# Research grounded in local files (auto-creates store, uploads, cleans up)\nuv run scripts/research.py start \"How does auth work?\" --context ./src --output report.md\n\n# Filter context to specific file types\nuv run scripts/research.py start \"Analyze the Python code\" --context ./src --context-extensions py,md\n```\n\n## Use Cases\n\nThis tool turns any AI agent into a domain specialist. The async, multi-step synthesis produces expert-grade output -- not search results.\n\n### Trading \u0026 Finance (OpenClaw, Pi, any agent)\n\n```bash\n# Make your agent a trading analyst\nuv run scripts/research.py start \\\n  \"Analyze NVDA: bull/bear thesis, valuation metrics, institutional positioning, and risk factors\" \\\n  --output nvda-analysis.md\n\n# Due diligence grounded in your portfolio\nuv run scripts/research.py start \\\n  \"Evaluate this portfolio for concentration risk and sector exposure\" \\\n  --context ./portfolio.csv --output due-diligence.md\n```\n\n### Competitive Intelligence\n\n```bash\n# Deep-dive a competitor using your own product docs as context\nuv run scripts/research.py start \\\n  \"How does Competitor X compare to our product? Where are we ahead, where are we behind?\" \\\n  --context ./docs --output competitive-analysis.md\n```\n\n### Software Architecture (Claude Code, Codex, Amp)\n\n```bash\n# Research trade-offs for an architecture decision\nuv run scripts/research.py start \\\n  \"Compare event sourcing vs CQRS vs traditional CRUD for our domain model. \\\n   Which approach fits best given our codebase?\" \\\n  --context ./src --output adr-research.md\n\n# Security audit prep grounded in your dependencies\nuv run scripts/research.py start \\\n  \"Research known CVEs and threat models relevant to our dependency tree\" \\\n  --context ./package-lock.json --output security-research.md\n```\n\n### Design \u0026 UX Research\n\n```bash\n# Research design patterns grounded in your existing styles\nuv run scripts/research.py start \\\n  \"Research accessible color systems, type scales, and motion design principles \\\n   for a dark-first design system\" \\\n  --context ./src/styles --output design-research.md\n```\n\n### Research \u0026 Analysis (any agent)\n\n```bash\n# Academic-style literature review\nuv run scripts/research.py start \\\n  \"Systematic review of retrieval-augmented generation architectures published in 2025-2026\" \\\n  --report-format comprehensive --output rag-review.md\n\n# Market sizing for a product idea\nuv run scripts/research.py start \\\n  \"TAM/SAM/SOM analysis for AI-powered code review tools targeting enterprise\" \\\n  --output market-sizing.md\n\n# Regulatory compliance research grounded in your architecture\nuv run scripts/research.py start \\\n  \"What SOC 2 Type II controls apply to our system architecture?\" \\\n  --context ./docs/architecture --output compliance-research.md\n```\n\n## Onboarding\n\nFirst-time setup for humans and agents:\n\n```bash\n# Quick config check\nuv run scripts/onboard.py --check\n\n# Interactive setup wizard (humans)\nuv run scripts/onboard.py --interactive\n\n# Capabilities manifest (agents)\nuv run scripts/onboard.py --agent\n```\n\nFor AI agents integrating this skill, see [AGENTS.md](AGENTS.md) for structured capabilities, decision trees, output contracts, and common workflows.\n\n## Features\n\n### Deep Research (`scripts/research.py`)\n\nStart background research jobs, check status, and save reports.\n\n```bash\nuv run scripts/research.py start \"your question\"       # Start research\nuv run scripts/research.py status \u003cid\u003e                  # Check progress\nuv run scripts/research.py report \u003cid\u003e --output file.md # Save report\n```\n\nKey flags:\n\n| Flag | Description |\n|------|-------------|\n| `--report-format FORMAT` | `executive_summary`, `detailed_report`, `comprehensive` |\n| `--store STORE_NAME` | Ground research in a file search store |\n| `--output FILE` | Block until complete, save report to file |\n| `--output-dir DIR` | Block until complete, save structured results to directory |\n| `--timeout SECONDS` | Maximum wait time when polling (default: 1800) |\n| `--no-adaptive-poll` | Use fixed polling interval instead of history-adaptive |\n| `--follow-up ID` | Continue a previous research session |\n| `--no-thoughts` | Hide intermediate thinking steps |\n| `--context PATH` | Auto-create ephemeral store from local files for RAG-grounded research |\n| `--context-extensions EXT` | Filter context uploads by extension (e.g. `py,md`) |\n| `--keep-context` | Keep the ephemeral context store after research completes |\n| `--dry-run` | Estimate costs without starting research |\n| `--format {md,html,pdf}` | Output format (default: md; pdf requires weasyprint) |\n| `--prompt-template {typescript,python,general,auto}` | Domain-specific prompt prefix (default: auto-detect from context) |\n| `--depth {quick,standard,deep}` | Research depth: quick (~2-5min), standard (~5-15min), deep (~15-45min) |\n| `--max-cost USD` | Abort if estimated cost exceeds limit |\n| `--input-file PATH` | Read query from file (for long/complex queries) |\n| `--no-cache` | Skip cache, force fresh research |\n\n### Output Formats\n\nExport research reports as Markdown, HTML, or PDF:\n\n```bash\nuv run scripts/research.py start \"Analyze the API\" --format html --output report.html\nuv run scripts/research.py start \"Architecture review\" --format pdf --output report.pdf\n```\n\nHTML includes a dark-themed stylesheet. PDF requires `pip install weasyprint` (graceful error if missing). Markdown is always the canonical format; other formats are converted from it.\n\n### Prompt Templates\n\nAuto-detect or specify domain-specific prompt optimization:\n\n```bash\n# Auto-detect from file extensions in --context path\nuv run scripts/research.py start \"How does auth work?\" --context ./src --prompt-template auto\n\n# Explicit: optimize for TypeScript/JavaScript codebases\nuv run scripts/research.py start \"Analyze the API layer\" --context ./src --prompt-template typescript\n\n# Explicit: optimize for Python codebases\nuv run scripts/research.py start \"Review the data pipeline\" --context ./src --prompt-template python\n```\n\nTemplates instruct the research model to focus on domain-specific patterns (type signatures, module structure, framework conventions, etc.).\n\n### Cost Estimation\n\nPreview estimated costs before running research:\n\n```bash\nuv run scripts/research.py start \"Analyze the codebase\" --context ./src --dry-run\n```\n\nEstimates are heuristic-based (the Gemini API does not return token counts). After research completes with `--output-dir`, `metadata.json` includes post-run usage estimates based on actual output size and duration.\n\n### Adaptive Polling\n\nWhen `--output` or `--output-dir` is used, the script polls the Gemini API with history-adaptive intervals:\n\n- Completion times are recorded in `.gemini-research.json` (last 50 entries, separate curves for grounded vs non-grounded research)\n- With 3+ data points: polls aggressively during the likely completion window (p25-p75), slowly in the tail\n- Without history: uses a fixed escalating curve (5s, 10s, 30s, 60s)\n- All intervals clamped to [2s, 120s]\n\n### Structured Output (`--output-dir`)\n\nResults are saved to a structured directory:\n\n```\n\u003coutput-dir\u003e/research-\u003cid\u003e/\n  report.md          # Full final report\n  metadata.json      # Timing, status, output count, sizes\n  interaction.json   # Full interaction data\n  sources.json       # Extracted source URLs/citations\n```\n\nA compact JSON summary (under 500 chars) is printed to stdout for agent consumption.\n\n### File Search Stores (`scripts/store.py`)\n\nCreate and manage file search stores for RAG-grounded research.\n\n```bash\nuv run scripts/store.py create \"My Project Docs\"\nuv run scripts/store.py list\nuv run scripts/store.py query \u003cstore-name\u003e \"What does the auth module do?\"\nuv run scripts/store.py delete \u003cstore-name\u003e [--force]\n```\n\n### File Upload (`scripts/upload.py`)\n\nUpload files or directories to a file search store.\n\n```bash\nuv run scripts/upload.py ./src fileSearchStores/abc123\nuv run scripts/upload.py ./docs \u003cstore-name\u003e --smart-sync --extensions py,ts,md\n```\n\n`--smart-sync` skips files that haven't changed (hash comparison). 36 file extensions are natively supported; common programming files are uploaded as `text/plain` via fallback. 100 MB per file limit.\n\n### Session Management (`scripts/state.py`)\n\n```bash\nuv run scripts/state.py show       # Full workspace state\nuv run scripts/state.py research   # Research sessions only\nuv run scripts/state.py stores     # Stores only\nuv run scripts/state.py clear      # Clear state\nuv run scripts/state.py --json show  # JSON output for agents\n```\n\n### Non-Interactive Mode\n\nAll confirmation prompts (`store.py delete`, `state.py clear`) are automatically skipped when stdin is not a TTY, allowing AI agents and CI pipelines to call these commands without hanging.\n\n### Output Convention\n\nAll scripts follow a dual-output pattern:\n- **stderr**: Rich-formatted human-readable output (tables, panels, progress)\n- **stdout**: Machine-readable JSON for programmatic consumption\n\nPipe `2\u003e/dev/null` to hide human output; pipe stdout for clean JSON.\n\n## Workflow Example\n\n```bash\n# 1. Create a file search store\nSTORE_JSON=$(uv run scripts/store.py create \"Project Codebase\")\nSTORE_NAME=$(echo \"$STORE_JSON\" | python3 -c \"import sys,json; print(json.load(sys.stdin)['name'])\")\n\n# 2. Upload your documents\nuv run scripts/upload.py ./docs \"$STORE_NAME\" --smart-sync\n\n# 3. Query the store directly\nuv run scripts/store.py query \"$STORE_NAME\" \"How is authentication handled?\"\n\n# 4. Start grounded deep research (blocking, saves to directory)\nuv run scripts/research.py start \"Analyze the security architecture\" \\\n  --store \"$STORE_NAME\" --output-dir ./research-output --timeout 3600\n```\n\n## Architecture\n\n```\nPython CLI scripts (uv run)\n    |\n    +-- research.py  (deep research jobs)\n    +-- store.py     (file search store CRUD)\n    +-- upload.py    (file/directory upload)\n    +-- state.py     (workspace state management)\n    |\n    v\ngoogle-genai Python SDK\n    |\n    v\nGoogle Gemini API\n    +-- Deep Research Agent (long-running research)\n    +-- File Search API (RAG grounding)\n    |\n    v\n.gemini-research.json (local workspace state)\n```\n\n## Security \u0026 Trust\n\nThis skill contains **no obfuscated code, no binary blobs, and no minified scripts**. Every file is readable Python using [PEP 723](https://peps.python.org/pep-0723/) inline script metadata, executed via `uv run` with explicit dependency declarations -- nothing is hidden.\n\n- **Network access**: Google Gemini API only (requires your API key via environment variable)\n- **No telemetry**: No analytics, no data collection, no phone-home behavior of any kind\n- **Fully auditable**: `scripts/` contains every line of executable code; read it in five minutes\n- **MIT licensed**: [LICENSE](LICENSE) -- fork it, audit it, vendor it\n- **Security policy**: [SECURITY.md](SECURITY.md) -- responsible disclosure via GitHub Security Advisories\n\nIn the wake of the [ToxicSkills disclosure](https://skills.sh/blog/toxicskills), we believe explicit transparency is table stakes for any agent skill. If something looks wrong, [open an issue](https://github.com/24601/agent-deep-research/issues).\n\n## Known Issues\n\n### Store-grounded deep research may fall back to web-only mode\n\nWhen using `--store` with `research.py start`, the Gemini Interactions API occasionally rejects the file search store configuration. The script automatically retries without the store, falling back to web-only deep research. The retry logic works correctly, but the fallback research job may take longer than expected (potentially exceeding `--timeout`).\n\n**Workaround**: If store-grounded research times out, use `research.py status \u003cid\u003e` to check if the job completed on Gemini's side, then `research.py report \u003cid\u003e` to save results. Alternatively, query the store directly with `store.py query` for faster RAG-grounded answers that don't require the deep research agent.\n\nThis applies to both `--store` and `--context` (which creates an ephemeral store under the hood). This is an upstream issue with the experimental Gemini Interactions API, not a bug in this skill.\n\n## References\n\n- `references/online_docs.md` -- Links to official Google API documentation\n- `references/file_search_guide.md` -- Validated MIME types and upload compatibility\n- `docs/file-search-mime-types.md` -- Full MIME type test methodology and results\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, code style, and PR process.\n\n## Security\n\nTo report a vulnerability, use [GitHub Security Advisories](https://github.com/24601/agent-deep-research/security/advisories/new). See [SECURITY.md](SECURITY.md) for details.\n\n## Community\n\n- [GitHub Issues](https://github.com/24601/agent-deep-research/issues) -- bug reports and feature requests\n- [GitHub Discussions](https://github.com/24601/agent-deep-research/discussions) -- questions and ideas\n\n## Credits\n\nThis project was originally forked from [allenhutchison/gemini-cli-deep-research](https://github.com/allenhutchison/gemini-cli-deep-research). See [CREDITS.md](CREDITS.md) for full attribution.\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F24601%2Fagent-deep-research","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F24601%2Fagent-deep-research","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F24601%2Fagent-deep-research/lists"}