coral-intern

A minimalist CLI that turns Claude Code or OpenAI Codex into your research intern. Run one command, get a browser terminal where you can tell an AI agent:

"Start a new project on transformer attention sinks."

…and watch it create the GitHub repo, scaffold a LaTeX paper on Overleaf, and start drafting — all from a clean black-and-white terminal in your browser.

  ╭───────────────────────────────╮
  │                               │
  │     ⌁  c o r a l - i n t e r n   │
  │                               │
  ╰───────────────────────────────╯
       your research, on autopilot

Why

A research project usually lives in two places: code on GitHub and the paper on Overleaf. coral-intern is the thinnest possible glue layer that lets a coding agent (Claude Code or Codex) drive both, while you talk to it from a browser terminal that looks and feels like a real shell.

No web app to deploy. No accounts to create. One CLI, one localhost page.

Install

One-line (recommended). Handles Node setup too — no prerequisites:

curl -fsSL https://raw.githubusercontent.com/Human-Agent-Society/coral-intern/main/install.sh | sh

Or, if you already have Node 20+:

npm install -g coral-intern

You'll also need one of the two coding-agent backends installed locally (coral-intern init will offer to install it for you):

| Backend | Install | Auth | |---------------|------------------------------------------------------|--------------------------------------------| | Claude Code | npm i -g @anthropic-ai/claude-code | claude login or ANTHROPIC_API_KEY | | OpenAI Codex | npm i -g @openai/codex | codex then "Sign in with ChatGPT" or OPENAI_API_KEY |

Run coral-intern doctor any time to check what's installed and configured.

Quick start

# 1. One-time setup — pick an agent, paste a GitHub token, done.
coral-intern init

# 2. Start a project.
coral-intern start my-paper

# Your browser opens at http://localhost:7878
# A terminal shows up. Talk to your intern:
#
#   > Read the paper outline in README.md and draft the introduction.
#   > Push the code, then update the LaTeX on Overleaf.
#   > Find three related papers and add them to references.bib.

That's it. Close the browser tab to end the session.

What start actually does

1. Creates ./<name>/ with a minimal LaTeX template (main.tex, references.bib, README.md).
2. Initializes a git repo, creates a public GitHub repo under your account, pushes the first commit.
3. Either builds an Overleaf import URL (using Overleaf's documented snip_uri endpoint) — one click and Overleaf clones the GitHub zip into a new project for you, works on free Overleaf accounts — or links the existing Overleaf project you passed via --overleaf-url.
4. Starts a local web server (default http://localhost:7878) with a terminal page. From the sidebar you can change the linked Overleaf URL at any time.
5. Launches claude or codex inside the project directory under a PTY, with MCP servers pre-wired so the agent can act on GitHub and Overleaf without leaving the chat.

Commands

| Command | What it does | |-------------------------------|------------------------------------------------------------------------------| | coral-intern | Default — re-attach to the coral-intern project in this directory (or the most recent one). Just type this when you cd into a project. | | coral-intern init | Interactive one-time setup. Pick agent, save GitHub token + (optional) Overleaf token to ~/.coral-intern/config.json. | | coral-intern doctor | Verify backends, tokens, and dependencies. | | coral-intern start <name> | Scaffold a new project, link GitHub + Overleaf, launch browser terminal. Refuses if you're already inside a coral-intern project (nested projects aren't supported, like git init in an existing repo). | | coral-intern start <name> --here | Use the current directory instead of creating ./<name>/. | | coral-intern start <name> --port 8000 | Override the web server port. | | coral-intern start <name> --agent codex | Override the agent for this session. | | coral-intern start <name> --overleaf-url <url> | Link an existing Overleaf project instead of being prompted. | | coral-intern start <name> --skip-overleaf | Skip the Overleaf prompt entirely. | | coral-intern start <name> --private | Create the GitHub repo as private. (Note: this disables one-click Overleaf import.) | | coral-intern open | Same as bare coral-intern — re-attach to the project here, or the last one. | | coral-intern --help | Show all commands. |

Configuration

Stored at ~/.coral-intern/config.json:

{
  "agent": "claude",
  "github": { "token": "ghp_…", "username": "you" },
  "overleafGitToken": null,
  "port": 7878,
  "lastProject": "/Users/you/projects/my-paper"
}

Anything sensitive (the GitHub PAT) is chmod 600. Delete the file to start over.

GitHub token scopes

Create a fine-grained PAT at https://github.com/settings/personal-access-tokens with:

• Repository permissions: Contents (R/W), Metadata (R), Pull requests (R/W)
• Account permissions: leave default
• Or use a classic PAT with repo scope.

Overleaf

By default coral-intern uses zero Overleaf API — it just stores a link to your project so the agent knows where the paper lives, and (for new projects) generates Overleaf's documented snip_uri import URL. Free Overleaf accounts work end-to-end.

To let the agent push edits directly to Overleaf (so you don't have to re-import or copy/paste), you need an Overleaf Premium git token:

1. Get the token: Overleaf → Account Settings → Git Integration → New Token. Overleaf Premium is required — MIT, Stanford, and many other schools provide it free at overleaf.com/edu.
2. Save it: either re-run coral-intern init (4th step), or — easier — from the web terminal sidebar click "Connect for direct edits" and paste the token.
3. Refresh the page so the agent picks up the new token, then ask it to push.

When configured, the Overleaf row in the sidebar shows a green "direct push enabled" badge. The agent uses the overleaf_push MCP tool to clone your project, overlay your local .tex/.bib/figures, commit, and push back — no duplicate projects.

Managing GitHub + Overleaf from the web terminal

The sidebar's resource rows are fully interactive:

• GitHub · click the pencil → modal lets you (a) link any existing repo by URL or owner/repo, (b) create a new repo under your account and push initial content, or (c) unlink.
• Overleaf · same pattern — link an existing project URL, generate a new one from your GitHub repo, or unlink. Plus the Connect for direct edits affordance for the premium token.

Both modals validate input, use your saved tokens, update CLAUDE.md / AGENTS.md so the agent sees the change immediately, and surface clear errors when something is wrong.

Publishing this CLI

For maintainers / forkers:

# 1. Bump version
npm version patch    # or minor / major

# 2. Build & test locally
npm run build
node dist/cli.js --help

# 3. Login to npm (one time)
npm login

# 4. Publish (runs tsc cleanly first via prepublishOnly)
npm publish --access public

To test before publishing:

npm pack                       # produces coral-intern-x.y.z.tgz
npm i -g ./coral-intern-*.tgz  # try it

To unpublish a broken patch within 72h:

npm unpublish coral-intern@<version>

Hosting the curl installer

install.sh lives at the repo root. The curl | sh one-liner in the install section just fetches it from GitHub's raw endpoint, so no extra hosting is needed — push the repo and the URL works.

Want a prettier URL like curl get.coral-intern.dev | sh? Two options:

• Cloudflare Worker / Netlify redirect pointing your custom domain to the GitHub raw URL. Five-minute setup.
• GitHub Pages: enable Pages on the repo and install.sh is served at https://human-agent-society.github.io/coral-intern/install.sh.

Either way, update the install-section URL in this README and you're done.

Development

git clone <your-fork>
cd coral-intern
npm install
npm run dev -- --help            # run via tsx, no build needed
npm run build && node dist/cli.js doctor

Layout:

src/
  cli.ts                   commander entry
  commands/
    init.ts                first-run wizard
    doctor.ts              health check
    start.ts               main project launcher
    open.ts                re-open last project
  config.ts                ~/.coral-intern/config.json reader/writer
  integrations/
    github.ts              octokit + simple-git
    overleaf.ts            snip_uri builder
  server/
    server.ts              express + ws on localhost
    pty.ts                 spawns the agent under node-pty
    public/                xterm.js terminal page
  mcp/
    config.ts              builds the MCP servers JSON the agent sees
    overleaf-server.mjs    tiny stdio MCP server exposing overleaf tools
  templates/research/      LaTeX skeleton copied into new projects
  util/
    log.ts                 chalk + ora wrappers

License

MIT