neoncodex

NeonCodex AI from your terminal: Claude Opus 5.5, GPT-5.5, Gemini, Grok, DeepSeek and 30+ models, with the same account, history and billing as neoncodex.io.

Install

npm install -g neoncodex

Needs Node.js 18 or later. Also available as ncx.

Sign in

neoncodex login        # paste a key from neoncodex.io/settings?tab=api
# or, in scripts and CI:
export NEONCODEX_API_KEY=nck_live_...

Usage

neoncodex run "Write a Python function to parse CSV files"
neoncodex run "Find the race condition" -m claude-opus-5-5 -e high
neoncodex run "Review this module" -f src/auth.ts src/session.ts
cat error.log | neoncodex run "What caused this error?"
neoncodex run "Write a README" -f package.json -o README.md
neoncodex run -c <chat-id> "Now add tests for it"     # continue a chat
neoncodex chat                                       # interactive, with follow-ups

Answers go to stdout; status goes to stderr. Ctrl+C stops the answer and cancels the task.

Coding agent

cd my-project
neoncodex agent "fix the failing tests"      # does the work, asks before running commands
neoncodex agent                              # interactive session (/plan, /ask, /undo, /exit)
neoncodex agent --plan "add rate limiting"   # explore and write a plan, change nothing
neoncodex agent --ask "how does auth work?"  # answer from the code, change nothing
neoncodex agent --undo                       # put back the files the last run changed

The agent reads and searches your project (including a local codebase index for finding code by what it does), edits files, and runs commands such as tests and builds. It asks before each command, file change, web page and MCP tool (see Approvals below), or pass --yes to allow all. It follows AGENTS.md, CLAUDE.md, .cursorrules and .cursor/rules.

For scripts and CI: neoncodex agent --yes --json "update the changelog" prints { status, output, files, steps }.

Custom modes

A mode is a Markdown file with instructions and a tool level. Use it with --mode <name> or /mode <name> in an interactive session.

neoncodex modes new "Security review" --tools read   # creates .neoncodex/modes/security-review.md
neoncodex modes                                       # list built-in, project and your modes
neoncodex agent --mode security-review "check the login flow"

---
name: Security review
description: Looks for security bugs, changes nothing
tools: read          # read | edit | all
model: claude-sonnet-5-5
web: true            # may open web pages
browser: false       # may drive a browser (tools: all only)
---
Look for injection, auth and secret-handling bugs. List them by severity with file and line.

Project modes live in .neoncodex/modes/ (commit them to share with your team); yours in ~/.neoncodex/modes/. A mode can only narrow what the agent may do: commands, file changes and web pages still ask as usual.

Hooks

Your own commands at points in a run: format after every edit, block risky commands, run the tests before the agent says it is done.

{ "hooks": {
    "before_tool":   [{ "match": "run_command", "command": "node .neoncodex/check-command.js" }],
    "after_tool":    [{ "match": "edit_file|write_file", "command": "npx prettier --write \"$NEONCODEX_FILE\"" }],
    "session_start": [{ "command": "git status --short" }],
    "stop":          [{ "command": "npm test --silent", "timeout": 300 }] } }

Put this in ~/.neoncodex/hooks.json (yours, every project) or .neoncodex/hooks.json (the project's). A hook gets the event as JSON on stdin and NEONCODEX_EVENT, NEONCODEX_TOOL, NEONCODEX_FILE, NEONCODEX_PROJECT_DIR. Exit 0 is fine (for session_start and prompt_submit, stdout becomes context for the agent). Exit 2 blocks: before_tool stops the tool and the agent sees stderr as the reason, prompt_submit stops the message, after_tool sends stderr back as feedback, and stop sends the agent back to fix what stderr says (up to 3 times). Events: session_start, prompt_submit, before_tool, after_tool, stop.

A project's hooks run only after you trust them, and you are asked again whenever the file changes: the agent asks on its first run, or use neoncodex hooks trust. --yes never trusts them; in CI pass --trust-project for repositories you control. neoncodex hooks shows what runs.

Parallel agents in git worktrees

neoncodex agent --parallel 3 "make the import faster"                  # 3 agents, same model
neoncodex agent --models claude-sonnet-5-5,gpt-5.5 "fix issue #42"     # one agent per model
neoncodex agent --worktree "try a bigger refactor"                      # one agent, away from your folder

Each agent works in its own git worktree on a new branch (in ~/.neoncodex/worktrees/, starting from your last commit), so they don't touch each other or your folder. When they finish you see what each changed and pick one: apply it to your folder (uncommitted), keep it as a branch, or decide later.

neoncodex worktrees                 # list, with files changed
neoncodex worktrees diff <id>       # see the changes
neoncodex worktrees apply <id>      # put them in your folder
neoncodex worktrees keep <id>       # commit on its branch, remove the worktree
neoncodex worktrees discard <id>    # remove it and its branch (--all for every one)

Browser

In Agent mode the agent can use a real browser (Chrome, Edge or Chromium, if installed) to check pages that need JavaScript or the app you are building on localhost: open, read, click, type and take screenshots. It uses a separate, temporary profile (none of your cookies or passwords), asks before each new site, never types into password or card fields, and blocks downloads and file uploads. --headless-browser hides the window, --no-browser turns it off. Set NEONCODEX_BROWSER to use a specific browser.

MCP servers. neoncodex mcp add github npx -y @modelcontextprotocol/server-github (or neoncodex mcp add docs https://example.com/mcp) gives the agent those tools. Servers in a project's .mcp.json or .cursor/mcp.json are found too and ask for approval first. neoncodex mcp lists them.

Cloud Agents

Hand the work in your repository to a Cloud Agent and close your laptop. The agent continues in a cloud sandbox from your last pushed commit, with your unpushed commits and uncommitted changes (new files too, unless git ignores them), and opens a pull request when it is done.

neoncodex cloud handoff "finish the migration and make the tests pass"
neoncodex cloud handoff --branch-only --watch "add the missing tests"
neoncodex cloud list                  # your recent runs
neoncodex cloud status <id> --watch   # follow one
neoncodex cloud diff <id>             # what it changed, as a git diff
neoncodex cloud pull <id> --worktree  # bring its branch back, in a new worktree
neoncodex cloud open-pr <id>          # open the pull request for a branch-only run
neoncodex cloud stop <id>

Works with repositories on GitHub, GitLab, Bitbucket and Azure DevOps that you connected at neoncodex.io (Connectors). Before anything is uploaded you see the repository, the commit it starts from and the size of your changes. Files that look like credentials (.env, private keys, .npmrc) stop the hand-off unless you add --allow-sensitive. --transcript <file> sends the conversation so far as context. Ids can be shortened to their first 8 characters.

Scheduled tasks

Run a prompt automatically on a schedule, in your timezone. Each run starts a new task on your account.

neoncodex schedule create "Summarise yesterday's commits in acme/shop" --every weekday --at 09:00
neoncodex schedule create --cron "0 18 * * 5" --tz Europe/London -m claude-sonnet-5-5 < report-prompt.md
neoncodex schedule preview --every week --day fri --at 17:00   # check the times, save nothing
neoncodex schedule list                # active, paused or failing, and the next run
neoncodex schedule run <id>            # run it now
neoncodex schedule runs <id>           # history: status, credits, the task each run started
neoncodex schedule pause <id>          # and: resume, edit, delete, limits

--every takes hour, day, weekday, week, month or an interval such as 2h; --cron takes any 5-field cron expression. The timezone defaults to your computer's. The same schedules show at neoncodex.io (Settings, Scheduled Tasks) and in VS Code. Needs a personal API key with the tasks:write scope.

Plugins, deploys and phone control

neoncodex plugins sync           # modes, hooks and MCP servers from plugins on your account
neoncodex deploy --to vercel     # your build output, live on your own Vercel or Netlify account
neoncodex remote                 # a QR code to control the agent from your phone

Plugin hooks and local MCP servers always ask before they first run, and again when the plugin changes; --trust-plugins allows them in CI. deploy leaves out .env, .git, node_modules and key files and refuses files that contain secrets. Phone sessions are end-to-end encrypted: the key is in the QR code and never reaches the server.

Commands

| Command | Description | |---|---| | login / logout | Save or remove your API key | | whoami | Account, plan and token balance | | models | Models on your plan, with thinking levels | | run [prompt...] (ask) | Send a prompt and stream the answer | | chat | Interactive chat (/model, /effort, /persona, /file, /new, /exit) | | history | Recent chats | | get <id> [--thread] | Print an answer or a whole conversation | | cancel <id> | Stop a running task | | personas | Your personas | | usage | Today's usage and balance | | config | Default --model, --effort, --api-url | | agent [task...] (code) | Coding agent in the current folder (--mode, --plan, --ask, --yes, --worktree, --parallel, --models, --undo) | | modes [list\|new] | Custom modes | | hooks [list\|trust\|untrust] | Hooks that run during agent runs | | worktrees [list\|diff\|apply\|keep\|discard] | Parallel agents' worktrees | | permissions [list\|remove\|reset] | What the agent may do here without asking | | mcp [list\|add\|remove] | MCP servers for the agent | | cloud [handoff\|list\|status\|diff\|pull\|open-pr\|stop] | Cloud Agents: continue local work in the cloud and bring results back | | plugins [list\|sync\|forget] | Plugins from your account | | deploy [folder] | Deploy a static site to your Vercel or Netlify account (--to, --project, --yes, --no-wait) | | deployments | Your recent deploys | | remote | Control the agent from your phone (end-to-end encrypted) |

Options for run

| Option | Description | |---|---| | -m, --model <id> | Model ID (see neoncodex models), default auto | | -e, --effort <level> | Thinking level: none, low, medium, high, xhigh, max (by model) | | -f, --file <paths...> | Attach text, code or image files | | -p, --persona <name> | Apply a persona | | -c, --continue <id> | Continue an existing chat | | -o, --output <file> | Also save the answer to a file | | --no-stream | Print only when complete | | --json | JSON result for scripts | | -q, --quiet | No status lines | | --deep / --no-deep | Always or never use a Deep Review (paid plans). By default NeonCodex decides. |

Full documentation: neoncodex.io/docs/integrations/cli

Approvals

Before the AI runs a command, changes a file, opens a web page or uses an MCP tool, it asks you in the terminal:

Open this web page?
  Open docs.python.org
    https://docs.python.org/3/library/asyncio.html
  1  Allow once
  2  Allow docs.python.org for this conversation
  3  Always allow docs.python.org
  4  Deny, and tell the AI what to do instead

File changes show a colored diff first. "Always" for commands and file changes applies to the current folder; for web sites it applies everywhere and is saved on your account, so neoncodex.io, VS Code and the browser extension stop asking too. See or remove what you allowed with neoncodex permissions.

neoncodex run and chat also show the approvals for cloud tasks (a web page the AI wants to read, a change in a connected app, code in the sandbox) when you run them in a terminal. In scripts and pipes nobody can answer, so cloud tasks follow your account's setting for unattended runs, the agent makes file changes (undo with neoncodex agent --undo, or skip them with --ask-edits) and skips everything else unless you pass --yes.

What's new in 1.8.0

• Plugins: modes, hooks and MCP servers from plugins you install at neoncodex.io (neoncodex plugins, --trust-plugins).
• neoncodex deploy and neoncodex deployments: deploy your build output to your own Vercel or Netlify account.
• neoncodex remote: control the agent from your phone through an end-to-end encrypted session.

What's new in 1.7.0

• neoncodex cloud handoff: continue your local work in a Cloud Agent, with your unpushed commits and uncommitted changes.
• neoncodex cloud list, status, diff, pull, open-pr and stop for Cloud Agent runs, including Bitbucket and Azure DevOps repositories.

What's new in 1.6.0

• Custom modes: your own modes with instructions, a tool level and a model (neoncodex modes, --mode, /mode).
• Hooks: run your commands before and after tools, at the start, on each message and when the agent finishes (neoncodex hooks).
• Parallel agents in git worktrees: --parallel, --models, --worktree and neoncodex worktrees.
• Browser control: the agent can open, read, click and type in a real browser, with your approval for each site.
• --trust-project for CI runs that should use the repository's hooks and MCP servers.

What's new in 1.5.0

• Claude Sonnet 5.5 is supported. It always thinks, so there is no off switch: -e none is its lowest level (minimal), and low to max think more. neoncodex models shows this.
• neoncodex models marks models that always think.

What's new in 1.4.0

• Approvals everywhere: allow once, for this conversation, always, or deny and say what to do instead. File changes are shown as a diff before they are made.
• The agent can open web pages (fetch_url), one site at a time with your approval.
• Cloud tasks started from the terminal show their approval requests.
• neoncodex permissions lists and removes what you always allow.

What's new in 1.3.0

• Tidier command output in the agent, and a notice when a new CLI version is available.

What's new in 1.2.0

• neoncodex agent: a coding agent that edits files and runs commands in your project, with Plan and Ask modes, approvals, undo, JSON output for CI, and MCP servers (neoncodex mcp).

What's new in 1.1.0

• Current models, including Claude Opus 5.5 and Grok 4.7, loaded live from your account.
• Thinking levels (-e), personas (-p), multiple files and images (-f).
• chat for interactive conversations, and -c to continue any chat from the web app, VS Code or the browser extension.
• Deep Review progress shown while sub-agents work.
• Ctrl+C now cancels the task on the server.
• --json, --quiet, cancel, personas, get --thread.
• Fixed: --file was rejected by the API; config --model was ignored; crashes on Node 18.
• The API key is sent only in the Authorization header and the config file is private (0600).
• Only one dependency (commander).

MIT License