Move to a terminal driven integration to have better interactions
This commit is contained in:
@@ -1,232 +1,110 @@
|
||||
# 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.
|
||||
Launch and resume [Claude Code](https://claude.com/product/claude-code) sessions
|
||||
for your project from Nova's sidebar.
|
||||
|
||||
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.
|
||||
Chat happens in a terminal, where Claude Code's own interface handles questions,
|
||||
plans and long output properly. Nova's job is everything around it: which
|
||||
sessions exist, how to get back into one, and which account you're on.
|
||||
|
||||
## 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)
|
||||
- Nova 10 or later (built against Nova 14)
|
||||
- Claude Code installed (`~/.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.
|
||||
2. If it says *Not signed in*, click it and choose how to sign in.
|
||||
3. Press **⌘⇧L** — the launch command is copied to your clipboard.
|
||||
4. Open a terminal in Nova and paste it.
|
||||
|
||||
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 |
|
||||
That's a normal `claude` session, in your project directory, with whatever model
|
||||
and permission mode the sidebar shows.
|
||||
|
||||
## 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.
|
||||
```
|
||||
Claude
|
||||
Account [email protected] · Pro
|
||||
Model Opus
|
||||
Permissions Ask each time
|
||||
Sessions
|
||||
▾ fix the parser bug 2h ago
|
||||
Copy Resume Command
|
||||
Copy Resume + Remote Control
|
||||
Reveal Session File
|
||||
▸ add a --version flag yesterday
|
||||
```
|
||||
|
||||
**Sessions** lists this project's conversations, newest first, labelled with
|
||||
their opening prompt. Sessions you started in a terminal appear here too — it is
|
||||
Claude Code's own store (`~/.claude/projects/`), not a separate list.
|
||||
|
||||
Double-click a session to copy its resume command, or expand it for more:
|
||||
|
||||
| Action | What it copies |
|
||||
| --- | --- |
|
||||
| Copy Resume Command | `cd <project> && claude --resume <id>` |
|
||||
| Copy Resume + Remote Control | The same, plus `--remote-control` |
|
||||
| Reveal Session File | *(opens the transcript in Finder)* |
|
||||
|
||||
The list refreshes when the section becomes visible, or from the header button.
|
||||
|
||||
## Why the clipboard?
|
||||
|
||||
Nova provides no terminal API to extensions — an extension cannot open a
|
||||
terminal tab or type into one. So the extension prepares the exact command and
|
||||
hands it to you; you paste it wherever you want it, including Nova's own
|
||||
terminal. One paste, and the session is completely ordinary: resumable from any
|
||||
terminal, and drivable with `--remote-control`.
|
||||
|
||||
## 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 | |
|
||||
| New Session… | ⌘⇧L |
|
||||
| Resume Session… | |
|
||||
| Refresh Sessions | |
|
||||
| Copy File Reference for Claude (Editor menu) | |
|
||||
| Set Model… / Set Permission Mode… | |
|
||||
| Sign In… / Sign Out / Show Account Status | |
|
||||
| Set API Key… / Clear Stored API Key | |
|
||||
|
||||
**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.
|
||||
**Copy File Reference for Claude** puts `@path/to/file` on the clipboard for
|
||||
pasting into a session — Claude Code resolves `@` paths against the project.
|
||||
|
||||
**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.
|
||||
## Signing in
|
||||
|
||||
**Resume Session…** lists this project's recent Claude Code sessions, labelled
|
||||
with their opening prompt, including ones started in a terminal.
|
||||
Authentication is handled by Claude Code itself; the extension never sees your
|
||||
credentials. **Sign In** offers your Claude subscription, an Anthropic Console
|
||||
account, or opening a terminal to run `claude auth login` yourself — use that
|
||||
last one for SSO.
|
||||
|
||||
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`.
|
||||
|
||||
## 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:
|
||||
Model, effort, permission mode and the `claude` executable path are set in
|
||||
Extension Settings; Model and Permission Mode can be overridden per project.
|
||||
They are applied to the commands the extension builds, so a launched session
|
||||
matches what the sidebar shows. **Additional CLI arguments** are appended
|
||||
verbatim.
|
||||
|
||||
- **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
|
||||
## What's next
|
||||
|
||||
## 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.
|
||||
The [IDE bridge](docs/features/ide-bridge.md): a Node sidecar that lets the
|
||||
terminal session see Nova — the current selection, open files, and diffs
|
||||
reviewed in the editor rather than as terminal text.
|
||||
|
||||
## Development
|
||||
|
||||
```sh
|
||||
nova extension validate . # check the bundle
|
||||
nova extension validate . # check the bundle (makes network calls)
|
||||
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.
|
||||
See [`CLAUDE.md`](CLAUDE.md) for architecture and constraints, and
|
||||
[`docs/features/`](docs/features/README.md) for per-feature detail.
|
||||
|
||||
Reference in New Issue
Block a user