Academic Agent Toolkit (AAT)

One command to install academic research skills and paper search across all your AI coding agents.

Students and researchers use different AI agents (Claude Code, OpenCode, Cursor, Copilot, Codex). Each agent needs different config formats, different file locations, and different skill setups. AAT handles all of that so you can focus on your research.

What you get

All configured across every supported agent in one command. No manual JSON/TOML editing.

Installation

Prerequisites: Python 3.11+ and uv.

If you are not a Python developer, use the uvx option. It runs the latest published version from PyPI without making you manage a virtual environment.

Pick one:

# Recommended: run directly from PyPI, no permanent install
uvx academic-agent-toolkit doctor

# Persistent install: keeps the `aat` command available in your terminal
uv tool install academic-agent-toolkit
aat doctor

# Standard pip install
pip install academic-agent-toolkit
aat doctor

After install, run:

aat install
aat setup-keys
aat verify

Quick Start

aat doctor      # See what agents are detected
aat install     # Install everything (skills + MCP)
aat setup-keys  # Configure API keys interactively
aat verify      # Confirm everything works

How it works

New users — aat install downloads Academic Research Suite and Experiment Agent automatically, creates a private .env file for your API keys, installs one canonical skill in ~/.agents/skills/academic-research-suite, and configures Paper Search MCP in every detected agent.

Existing users — AAT adopts your existing ARS installation and Paper Search MCP registrations. It skips what you already have and only manages what's missing. Use --replace-skills or --replace-mcp if you want AAT to take over an existing setup.

The .agents/ layout is the source of truth. Agents with native skill directories get symlinks to the canonical .agents skill instead of duplicated copies.

Commands

API Keys

Paper Search MCP works without most keys, but some sources need credentials. AAT helps you set them up interactively with aat setup-keys.

Keys are stored in a single private file (~/.config/paper-search-mcp/.env by default). Paper Search MCP reads them automatically via PAPER_SEARCH_MCP_ENV_FILE. No keys are duplicated across agent configs.

Supported Agents

Skill adapters (agent-optimized routers for Academic Research Suite):

• Zed (~/.agents/skills/ native global skill)
• Claude Code
• OpenCode
• Cursor
• GitHub Copilot (~/.agents/skills/ and ~/.copilot/skills/ global skills)
• Codex

GitHub Copilot loads skills from ~/.agents/skills/ and ~/.copilot/skills/ globally, and from .github/skills/, .claude/skills/, and .agents/skills/ per project. AAT already installs the canonical skill to ~/.agents/skills/ and symlinks to ~/.copilot/skills/, so Copilot picks it up automatically. VS Code does not expose a global skills directory — it is configured for MCP only.

MCP configuration (Paper Search MCP registration):

• Claude Code
• OpenCode
• Cursor
• Codex
• VS Code (user and global)
• GitHub Copilot
• Zed

See docs/mcp-agent-matrix.md for the exact config format used per agent.

Install flags

Uninstall

aat uninstall

Removes only files AAT created. Your existing hand-written configs and skill directories are never touched. Optional flags:

• --remove-env also removes the Paper Search MCP env file
• --remove-managed-ars also removes AAT's downloaded ARS source

Where files live

Upstream projects

AAT is an integration layer. It bundles and configures these upstream projects with their permission:

• academic-research-skills by Imbad0202 — v3.10.0
• experiment-agent by Imbad0202 — v1.1.0
• paper-search-mcp by openags

Developer testing

Use two separate environments when developing AAT:

Local sandbox

From the repository root:

# Run the CLI from your local source tree
uv run aat doctor
uv run aat install --dry-run --yes
uv run aat verify

Use this before publishing. It tests the code you are editing locally, even if it is not on PyPI yet.

Production check from PyPI

Use this after publishing a release:

# Run the latest published version from PyPI
uvx academic-agent-toolkit doctor

# Or install it persistently like a real user would
uv tool install --force academic-agent-toolkit
aat doctor
aat install --dry-run --yes
aat verify

Use this to confirm that PyPI users receive the expected version and behavior.

License

MIT — see LICENSE.