# Claude for Nova

Claude Code inside [Nova](https://nova.app): a sidebar for the session, a live
transcript in an editor tab, and every tool call routed through an approval you
can review before it touches your files.

The extension drives the `claude` executable already installed on your machine,
speaking its streaming JSON protocol over stdio. Your existing sign-in, settings,
`CLAUDE.md`, skills, plugins, and MCP servers all apply — this is the same agent
you get in a terminal, wearing Nova's interface.

## Requirements

- Nova 10 or later (built against Nova 14; not exercised on older versions)
- [Claude Code](https://claude.com/product/claude-code) installed and on disk
  (`~/.local/bin/claude`, Homebrew, or a path you set in settings)

## Getting started

1. Open the **Claude** sidebar (the starburst in the sidebar rail).
2. If the Account row says *Not signed in*, click it and choose how to sign in.
3. Press **⌘⇧L**, or use the ✳︎ button in the sidebar header, and ask for something.

The first prompt starts a session in your project directory. The transcript opens
as a tab and updates as Claude works.

## Signing in

Authentication is handled by Claude Code itself — the extension never sees your
credentials. **Sign In** offers three routes:

| Route | What happens |
| --- | --- |
| Claude Subscription | Runs `claude auth login`, opens the authorization page in your browser, and relays the code back |
| Anthropic Console | The same flow with `--console`, for API-billed accounts |
| Open a Terminal | Runs `claude auth login` in a terminal window — use this for SSO or if the in-app flow stalls |

You can also store an API key with **Set API Key…**. It goes in the macOS
keychain and is passed to Claude Code as `ANTHROPIC_API_KEY`, taking precedence
over a signed-in account. **Clear Stored API Key** removes it.

## Approving tool use

In the default *Manual* permission mode, Claude asks before each tool that needs
permission. Every request appears in **Needs Approval** in the sidebar *and* as a
panel, so dismissing the panel never strands the session — the request waits
until you answer it from the sidebar's context menu.

### Reviewing a file change

When Claude wants to edit or create a file, the file **as it would be after the
change** opens in a tab. Review it there, and settle it with ordinary editor
gestures:

| Gesture | Result |
| --- | --- |
| **⌘S** save | Apply the change |
| **⌘W** close | Reject it |

The tab is editable, and that is the point: fix the variable name Claude got
wrong, delete the half you don't want, then save — **your** version is what gets
written, not Claude's. A notification carries the same choices, and they appear
as rows under the request in the sidebar; **Show Diff** gives the unified diff if
you'd rather see just what moved.

Prefer the old quick yes/no? Set *Reviewing file changes* to **Ask in a panel**.

**Allow for Session** adds an allow rule for that tool for the rest of the
session, so Claude stops asking about it.

Two tools are their own interaction surface rather than a yes/no gate, and get
purpose-built handling — see *Plan mode* and *Questions* below.

## Plan mode

**Plan with Claude… (⌘⇧P)** switches the session into plan mode and prompts you.
Claude researches and proposes but changes nothing. When it has a plan, the plan
opens in a tab and you choose:

| Choice | What happens |
| --- | --- |
| Approve — auto-accept edits | Plan accepted; the session moves to Accept Edits so Claude can work uninterrupted |
| Approve — ask before each edit | Plan accepted; you keep approving each change |
| Keep Planning… | Send it back for revision; Claude revises and re-presents |
| Show Plan Again | Re-open the plan |

When a plan is ready you get a **notification**, not a modal sheet — the plan tab
stays scrollable and editable while you decide. The same choices also appear as
rows under the request in **Needs Approval**, so you can dismiss the notification
and take your time.

### Giving feedback on a plan

The plan is an ordinary editable document, and there are three ways to respond —
they combine freely:

- **Edit the plan in its tab.** Rewrite, delete, or add steps directly. When you
  approve, your version is sent back and becomes the plan of record — Claude
  works from what you wrote, not its own draft. Unsaved edits count.
- **Highlight a passage**, then choose *Keep Planning…*. The selected lines are
  quoted back to Claude along with your note, so "this part is wrong" has an
  unambiguous referent.
- **Write Feedback…** opens a scratch tab you can type into freely — as many
  paragraphs, lists, and code snippets as you want. When you're done, choose
  **Send Feedback** in the sidebar. Nova gives extensions no multi-line field of
  their own, so the editor itself is the text box.

If you edit the plan *and* send feedback, your rewrite goes along with it, marked
authoritative.

Nothing is lost by ignoring the notification: the plan waits in **Needs Approval**
with its choices until you act. Plans are saved by Claude Code under
`~/.claude/plans/`, so you can reopen one later.

You can also stay in plan mode for a whole session by setting the permission
mode to *Plan*.

## Questions

When Claude needs a decision from you it asks a real question, and the options
appear in a Nova choice palette. Pick one — or **Other…** to type your own
answer. Multi-select questions let you toggle several options and then choose
*Done*. Your answer goes straight back to Claude as the tool's result.

## Permission modes

Change the mode any time from the Permissions row:

| Mode | Behaviour |
| --- | --- |
| Manual | Ask before each tool (default) |
| Accept Edits | File edits apply automatically; other tools still ask |
| Plan | Research only — Claude proposes, changes nothing |
| Auto | Claude decides what is worth asking about |
| Bypass | Approve everything. Only in a directory you trust |

## The sidebar

- **Session** — status, account, model, permission mode, and running cost.
  Double-click Model or Permissions to change them mid-session.
- **Needs Approval** — anything waiting on you, with its choices as rows
  underneath: Allow / Allow for Session / Review / Deny for an ordinary tool,
  or the approve-and-feedback options for a plan. Double-click a row to take it.
- **Activity** — every tool call, newest first. Double-click one that touched a
  file to open it.
- **Changed Files** — files Claude actually modified. Double-click to open, or
  use **Show Change…** to see the last edit as a diff.

## Commands

| Command | Shortcut |
| --- | --- |
| Ask Claude… | ⌘⇧L |
| Plan with Claude… | ⌘⇧P |
| Ask Claude About Selection… (Editor menu) | ⌃⌘L |
| Add File to Claude's Context (Editor menu) | |
| Add Files to Context… | |
| Show Transcript | |
| New Session / Resume Session… | |
| Stop Claude / End Session | |
| Set Model… / Set Permission Mode… | |

**Add Files to Context…** opens a file chooser — pick any files or folders in the
project and ask about them together, without opening them first.

**Ask Claude About Selection…** sends the file, the line range, and the selected
text with your question. Plain **Ask Claude** does the same automatically when
there is a selection — turn that off with the *Include the editor selection*
setting.

**Resume Session…** lists this project's recent Claude Code sessions, labelled
with their opening prompt, including ones started in a terminal.

## Settings

Model, effort, permission mode, and the `claude` executable path are set in
Extension Settings; Model and Permission Mode can also be overridden per project
in Project Settings. Other options:

- **Reviewing file changes** — an editable proposal tab, or a panel
- **Open the transcript automatically** when a session starts
- **Stream text as it is generated** — token-by-token output
- **Show thinking in the transcript**
- **Include the editor selection with prompts**
- **Additional CLI arguments** — appended to the `claude` command line

## How it works

```
Nova extension ──stdio (stream-json)──> claude --print
     │                                       │
     │  <── assistant / tool / result ───────┤
     ├──── control_response (allow/deny) ────┤
     └──── control_request (interrupt) ─────>┘
```

One `claude` process per window, launched with
`--input-format stream-json --output-format stream-json`. Session messages and
control traffic share the pipe: the CLI raises a `can_use_tool` control request
for each permission prompt, and the extension answers it with your decision.
Questions are answered by returning the choices as `updatedInput`; approving a
plan returns a `setMode` permission update, which is what moves the session out
of plan mode. Interrupts and mid-session model or permission changes travel the
same channel.

There is no bundled copy of Claude Code, no Node sidecar, and no network access
of its own — the extension only talks to the executable you already trust.

## Known limits

- Nova has no scriptable diff viewer, so proposed changes are shown as a unified
  diff in a scratch tab rather than in a side-by-side editor.
- Extension sidebars can only contain tree rows — there is no API for a
  multi-line field like the one in Nova's own Source Control sidebar. Feedback
  is written in a scratch tab instead, and decisions are tree rows.
- Ordinary tool approvals still use a panel, since they are a quick yes/no.
- Questions and plan approvals are handled natively. Any *other* tool that
  needs its own interactive prompt is declined with an explanation — run those
  from a terminal.
- The transcript is a Markdown document, so it renders text, not widgets.
- Sessions run in the workspace directory. Open a folder in Nova before asking.

## Development

```sh
nova extension validate .   # check the bundle
nova extension activate .   # load it into Nova for development
```

Extension logs (with `nova.inDevMode()` output) appear in Nova's Extension
Console. Keyboard shortcuts can be rebound in Preferences → Key Bindings if any
of the defaults collide with yours.