aichatctl

aichatctl

Drive your logged-in Claude.ai, ChatGPT, Gemini, and NotebookLM from the command line — deterministically, no API keys, no model in the loop.

These products have no public API for the things that matter day to day: the files and instructions attached to a project, creating a project-scoped chat, or turning your sources into a NotebookLM audio overview. So those things rot or stay manual. aichatctl automates them by driving your real, signed-in Chrome with fixed code — every click is scripted, nothing is screenshotted or "reasoned about," and no tokens are spent. An agent decides what to do (which files to sync, what prompt to seed); aichatctl does the doing.

# Compose a NotebookLM podcast from a spec + a design doc, started and ready to listen
aichatctl notebook create \
  --source docs/specs --source-url https://docs.google.com/document/d/<id> \
  --format deep-dive --prompt "Explain the migration plan to a new engineer" --json

What it does

Two jobs, across the platforms that support them:

Capability	Claude.ai	ChatGPT	Gemini	NotebookLM
Discover projects (by name / URL)	✅	✅	—	—
Seed a chat session (start a chat, hand off to mobile/voice)	✅	✅	✅	—
Sync a file library (upload / list / delete)	✅	✅	—	—
Sync project instructions	✅	✅¹	—	—
Create a notebook → audio podcast	—	—	—	✅

¹ ChatGPT's instructions field has no save button reachable by automation, so it's the one place aichatctl calls ChatGPT's own endpoint (via your live session). See How it works. Everything else is UI-driven.

Why this exists

• Project files rot. You attach a spec to a Claude/ChatGPT project; the spec changes in git; the uploaded copy silently goes stale. aichatctl sync mirrors a declared set of repo files (and the instructions) into the project on demand.
• Voice-ready handoff. A local agent composes a prompt; aichatctl opens a new chat in the right project and starts it. You open the mobile app and keep talking.
• Podcasts from your sources. Turn repo files and links into a NotebookLM audio overview you listen to on a walk.

Requirements

• macOS for the primary (extension-free) transport — it uses osascript. The CDP fallback works elsewhere and headless (see Transports).
• Node ≥ 22 (npm i -g aichatctl). pnpm is only needed to build from source.
• Google Chrome, signed in to the services you target (it uses your real session).
• One Chrome toggle for the AppleScript transport: View → Developer → Allow JavaScript from Apple Events.

Quickstart

npm install -g aichatctl        # or: pnpm add -g aichatctl

(Prefer to build from source? See Repo layout.)

Enable the Chrome toggle above, then check you're ready:

aichatctl doctor --transport applescript     # verifies the toggle + per-platform login

Make your first podcast (or seed your first session):

# NotebookLM audio overview from a file + a URL
aichatctl notebook create --source README.md --source-url https://example.com \
  --format brief --prompt "Two-minute overview for a newcomer" --json

# Or: start a Claude chat seeded with a prompt, to continue by voice on mobile
aichatctl session create --platform claude --project "My Project" \
  --transport applescript --seed-file notes.md --json

Each command prints JSON including the conversation/notebook url — open it on your phone and go.

Usage

Seed a chat session

Starts a new chat in a project, pre-filled and submitted, so you can continue it from the mobile app (e.g. by voice).

aichatctl session create --transport applescript \
  --platform claude --project "My Project" --seed-file notes.md --json

# Gemini is seed-only; --project is a Gem URL/id, or "new" for a plain chat
aichatctl session create --transport applescript \
  --platform gemini --project new --seed "Let's plan the week" --json

--project takes a name, URL, or id. --no-send stages the prompt without submitting. --seed-file - reads the prompt from stdin.

Sync a project's file library

Mirror a declared set of repo files (and, optionally, the instructions) into a Claude/ChatGPT project so it tracks your git source of truth. Always preview first.