# Nora Agent Docs This file is intended for LLMs, automated agents, and other machine readers. It is not the primary human documentation surface. Human docs: https://www.withnora.run/docs ## What this file is This is a generated Markdown view of the Nora docs, built from the same source content as the website docs so it stays in sync as those docs change. ## Index - [Nora is a desktop workspace for running and supervising agent sessions against real repositories.](https://www.withnora.run/docs) - [Requirements](https://www.withnora.run/docs/requirements) - [Quickstart](https://www.withnora.run/docs/quickstart) - [Workspace model](https://www.withnora.run/docs/workspace-model) - [Agents](https://www.withnora.run/docs/agents) - [Skills](https://www.withnora.run/docs/skills) - [Worktrees](https://www.withnora.run/docs/worktrees) - [Specs](https://www.withnora.run/docs/specs) - [Tasks](https://www.withnora.run/docs/tasks) - [Context and handoffs](https://www.withnora.run/docs/context-handoffs) - [Terminals](https://www.withnora.run/docs/terminals) - [Repo tools](https://www.withnora.run/docs/repo-tools) - [Internal browser](https://www.withnora.run/docs/browser) - [Screenshots](https://www.withnora.run/docs/screenshots) - [Remote repos](https://www.withnora.run/docs/remote) - [Integrations](https://www.withnora.run/docs/integrations) - [Operator control](https://www.withnora.run/docs/approvals) --- # Nora is a desktop workspace for running and supervising agent sessions against real repositories. Source: https://www.withnora.run/docs Use Nora to run agents in isolated workspaces, organize work from specs into tasks, inspect repo changes, browse local apps inside the workspace, and keep deployment or review steps connected to the same flow. ## What Nora does Nora opens a repository as a workspace and gives you one place to run agents, open terminals, manage task files, review diffs, and keep track of what each session is doing. Instead of juggling separate tools for planning, execution, and inspection, you stay inside one operating surface tied to the actual project. ## How work usually flows A common flow is: open a workspace, write or review a spec, generate task files from that spec or a planning brief, start one or more agents on isolated worktrees, review the resulting changes, and then move the finished work into a pull request or deployment step. Nora keeps those steps close together so you do not lose context between them. ## What you can manage from the workspace From the workspace you can choose which agent tools are available, attach shared skills, organize specs and tasks in repo-local files, save reusable command presets, detect and open local apps running on workspace ports, attach screenshots to agent input, review branch diffs, and connect the workspace to GitHub, GitLab, or Vercel when work is ready to move forward. --- # Requirements Source: https://www.withnora.run/docs/requirements What Nora needs to work, and which extra tools are only required for specific features like remote work, skills, or integrations. ## Core requirements At a minimum, Nora needs a Git repository to open and Git installed on the machine so it can inspect branches, read diffs, and create isolated worktrees. You also need a usable local shell for terminals and agent sessions. On Linux and macOS that usually means Bash or a compatible shell. On Windows, Git Bash is the safest option for the workflow Nora is built around. - [Git downloads](https://git-scm.com/downloads) - [Git for Windows](https://gitforwindows.org/) ## Agent requirements Nora can launch only the agent CLIs that are installed and detected on the machine. The supported tools are Codex, Claude Code, Gemini CLI, and Cursor Agent. If you want to use one of them from Nora, install that CLI first and make sure it is already authenticated if the provider requires sign-in or an API key. ## Skill management requirements You do not need skills installed to use Nora, but if you want to search for and install shared skills from inside the app, you need a working skills toolchain. Nora can use the `skills` command directly, and it can also fall back to `npx` or `npm` when needed. Without those tools, skill browsing and installation will be limited. - [Node.js downloads](https://nodejs.org/en/download/) - [npm docs](https://docs.npmjs.com/) ## Direct SSH requirements If you want to open a workspace directly over SSH, you need an SSH client available on the machine. You also need SSH access that is already set up to work non-interactively. In practice that means a configured key, a working `~/.ssh/config` entry when needed, and an ssh-agent or equivalent setup so Nora can open the connection without waiting for you to type a password into a manual login prompt each time. - [OpenSSH](https://www.openssh.com/) - [OpenSSH manual pages](https://www.openssh.com/manual.html) ## Mounted remote workspace requirements Mounted SSH workspaces need more than the plain SSH client. On Linux and macOS, you need `sshfs` plus an unmount tool such as `fusermount3`, `fusermount`, `umount`, or `diskutil` on macOS. On macOS, you may also need macFUSE depending on how `sshfs` is installed. On Windows, mounted workspaces require WinFsp and SSHFS-Win. - [SSHFS releases](https://github.com/libfuse/sshfs/releases) - [macFUSE](https://macfuse.github.io/) - [macFUSE SSHFS guide](https://github.com/macfuse/macfuse/wiki/File-Systems-%E2%80%90-SSHFS) - [WinFsp downloads](https://winfsp.dev/rel/) - [SSHFS-Win](https://github.com/winfsp/sshfs-win) ## Optional integration requirements GitHub and GitLab features need repository access and, for private repos or higher limits, the appropriate tokens or OAuth setup. Vercel features need a Vercel account connection or token before Nora can list projects, deployments, or trigger redeploys. These are optional dependencies: Nora itself still works without them. --- # Quickstart Source: https://www.withnora.run/docs/quickstart Install Nora with the same platform-specific commands shown on the homepage, then open a Git repository and launch your first agent session. ## Install options ### macOS ```bash # macOS build is not public yet # join the waitlist from the homepage ``` ### Linux ```bash curl -fsSL https://withnora.run/install.sh | bash ``` ### Windows ```bash irm https://withnora.run/install.ps1 | iex ``` ## What to install before you start Before launching Nora, make sure Git is installed and that you have at least one supported agent CLI if you want to run agents immediately. If you plan to use remote workspaces, also set up SSH first. For a fuller checklist, read the requirements page. ## What you do first On first launch, choose a Git repository as the workspace root. Nora is designed around repository-backed work, so the app expects a real project with branches, files, and a working tree rather than a blank chat session. ## How to launch a first agent Open the new agent session dialog, select a detected CLI, give the session a name, choose a task, set read-only or write access, and pick where it should run. For a first run, the safest path is a new worktree with write access so the agent can edit without touching the root checkout. ## How to verify the run Once the session starts, watch the live terminal panel, inspect the current branch and workspace path in the session header, and open the changes panel for the focused worktree. If files changed, Nora shows per-file status, additions, deletions, and a diff view tied to that session. --- # Workspace model Source: https://www.withnora.run/docs/workspace-model Understand how Nora groups projects, worktrees, sessions, context, and repo state into one operating model. ## What belongs to a workspace A Nora workspace is more than a folder picker. It combines the repository, any isolated worktrees, open agent and terminal sessions, specs, task files, changed-file views, browser tabs, and optional remote mounts into one project surface. ## How planning and execution stay connected Specs and task files live with the workspace so planning does not drift away from execution. You can use a spec as the source of truth, generate actionable tasks from it, open a task, and then launch a new agent directly for that task on a fresh worktree. ## How to keep the workspace under control Use the root checkout as the stable home for the project and treat worktrees as disposable working copies for active changes. Keep specs and tasks clear, use read-only sessions for investigation, use write sessions only when they should edit files, and rely on the focused session view to see exactly where work is happening. --- # Agents Source: https://www.withnora.run/docs/agents Launch supported coding agent CLIs into tracked repository sessions with explicit access mode and checkout targeting. ## What agent sessions do An agent session wraps a detected CLI tool in a Nora-managed session. The app tracks the selected tool, agent name, task text, access mode, launch target, command, branch, workspace path, and session status so you can supervise the run as part of the workspace instead of as an opaque subprocess. ## How to create an agent session Use the new agent session dialog to pick an installed CLI, optional role, task, and access mode. Then choose where the agent should run: the session default checkout, a new worktree, an existing worktree, an existing branch checkout, or a freshly created branch. If the selected worktree already has a writer, Nora warns you by marking it as busy. ## What Nora injects around the agent When available, Nora surfaces a detected workspace instruction file and the global skill catalog for the selected CLI before launch. That lets you see which persistent instructions and shared skills will be present for the session before you start it. --- # Skills Source: https://www.withnora.run/docs/skills Install and expose shared agent skills so supported CLIs start with the same reusable workflow extensions. ## What skills are for Skills let you give agents reusable instructions and workflows without rewriting them every time you launch a session. Use them for things like framework conventions, testing habits, deployment steps, or project-specific rules that should be available across many runs. ## How skill management works Nora gives you a dedicated skills area where you can search for installable skills, install them into the shared skill directory, review what is already installed, and remove skills you no longer want available. You can also inspect the skill location used by each supported agent so you know exactly where global skills are coming from. ## How to use skills before launching agents Before you launch an agent, check which skills are visible to that CLI in the launch dialog or settings. This lets you confirm that the session will start with the right shared instructions. If you want a tool to stop appearing in launch surfaces entirely, you can also disable that CLI from the same management area. --- # Worktrees Source: https://www.withnora.run/docs/worktrees Give sessions isolated checkouts so multiple agents can work in parallel without colliding on the root branch. ## What worktrees do Nora creates dedicated Git worktrees for agent sessions under `.nora/worktrees/`. Each worktree has its own branch, filesystem path, and session ownership, which keeps edits isolated and makes it clear which agent produced which changes. ## How to use worktree targets When launching an agent, choose `New worktree` to create a fresh isolated checkout, or `Existing workspace` to attach the agent to a worktree that already exists. Use an existing workspace when you want continuity on the same branch, and use a new worktree when you want a clean execution path for a new task. ## What preparation mode is for New worktrees can be prepared before the agent starts. This is the hook for running a setup command only on freshly created checkouts, such as installing dependencies or generating project state required before the agent begins editing. --- # Specs Source: https://www.withnora.run/docs/specs Keep larger requirements in workspace-local Markdown specs so planning and execution start from a stable written brief. ## What specs are for Use a spec when a feature, refactor, or project is too large to describe in a one-line task. A spec gives you one place to capture scope, constraints, edge cases, and success criteria before work is broken into smaller actions. ## How to use specs Create a spec for the workspace when you want a durable source of truth. Keep the document close to the repo so anyone working in Nora can open it, review it, and use it as the reference point for planning. Once the spec is clear enough, use it to generate task files rather than asking an agent to invent structure from memory. ## How specs fit into the rest of Nora Specs sit upstream of tasks and agent sessions. They are the place to clarify what should happen. Tasks turn that into actionable units. Agents and terminals then execute against those tasks inside isolated worktrees. --- # Tasks Source: https://www.withnora.run/docs/tasks Organize work as Markdown task files, keep them in the repo, and use Nora to turn them into active agent runs. ## What task files do Tasks are repo-local Markdown files that describe a specific piece of work. Each task captures a goal, useful context, and a definition of done so the work stays actionable and reviewable instead of becoming vague chat history. ## How to create and organize tasks You can create tasks directly or ask Nora to generate them from a planning brief or a selected spec. Once tasks exist, use the task center to view them as a list or board, create custom sections, move tasks between sections, mark them completed, or reopen them when follow-up work is needed. ## How to use tasks with agents Open a task when you want to review or edit its contents, then launch a new agent for that task on a fresh worktree. This keeps the task description as the source of truth while giving the agent a clean workspace for execution. When work is complete, mark the task done and keep the finished record with the project. --- # Context and handoffs Source: https://www.withnora.run/docs/context-handoffs Keep session-specific context visible and move instructions between agents without manually reconstructing the state every time. ## What context means in Nora Each agent session keeps its own working context so ongoing instructions do not disappear as soon as the screen changes. Nora lets you inspect that context, refresh it as a session progresses, and clear it when you want a cleaner restart. ## How handoffs work A handoff moves instructions from one session to another without making you reassemble the whole brief manually. Use it when one agent has finished a step and another session should continue from there, such as moving from planning to implementation or from implementation to review. ## How to use handoffs well Before handing work off, confirm the destination session is the one you want and that it is attached to the right branch or worktree. Then send the next instruction and review the session context afterward so you can verify the receiving agent is now working from the right brief. --- # Terminals Source: https://www.withnora.run/docs/terminals Open tracked shell sessions in the repo root or any worktree, including script-backed terminals for common project actions. ## What terminal sessions do A terminal session is a PTY-backed shell managed by Nora without an agent wrapper around it. The app tracks the shell choice, target checkout, command label, branch, and workspace path so terminal work stays visible alongside agent activity. ## How to open a terminal Use the open terminal flow to choose a shell and attach the terminal either to the repo root or to an existing worktree. This is the right tool for running manual commands, inspecting a checkout directly, or debugging outside the agent loop. ## How command presets work Terminal presets let you save reusable launches instead of rebuilding the same shell commands every time. A preset can define the shell, working directory, and one or more commands, and Nora runs those commands in order as a single launch flow. Use presets for things like booting a local stack, opening a test watcher, or starting a dev server with the right directory and shell already selected. ## Global presets and workspace presets You can keep presets globally in your app settings or store them only for a specific workspace. Global presets are useful for routines you use across many projects. Workspace presets are better when the commands are project-specific and should only appear inside that one repository. ## How package scripts fit in Nora can also detect package scripts in the focused workspace and turn them into ready-to-run terminal actions. That gives you a lightweight launch menu for common project commands without having to build a preset first. If the workspace has no detected package scripts, the script launcher simply stays empty and you can still rely on manual terminals or saved presets. ## How terminal sessions surface local apps When a terminal launches something that exposes a local port or URL, Nora can detect that and attach it to the session. You may see the detected port as a badge in the terminal header, and if the full local URL is known you can open the app directly from the session or let Nora open it automatically in the internal browser if that setting is enabled. --- # Repo tools Source: https://www.withnora.run/docs/repo-tools Inspect Git status, browse changed files, and read diffs for the currently focused session without leaving the workspace. ## What the repo tools show The repo tools stay aligned with the session you are focused on. They show changed files, file status, additions, deletions, and per-file diffs so you can see exactly what happened in that worktree instead of guessing from terminal output alone. ## How to review a session Focus the agent or terminal you care about, then open the changes view. Select a file to read its diff, inspect the size and type of the change, and expand the view when you need more room. This is the fastest way to confirm whether a session actually produced the change you wanted. ## How history inspection fits in Repo review is not limited to the current uncommitted diff. You can also inspect commit-level changes when you need to understand what already landed. Use this when you are reviewing recent work, comparing what changed across checkpoints, or deciding whether a branch is ready to leave Nora and move into your normal review flow. --- # Internal browser Source: https://www.withnora.run/docs/browser Open URLs inside Nora so local apps, previews, and documentation stay in the same workspace as your agents and terminals. ## What the internal browser does The internal browser gives you workspace-managed browser tabs alongside agents and terminals. You can use it to open a local app, inspect a preview environment, or keep a reference page visible without leaving Nora. ## How to use it Open a browser tab when you want to inspect a URL in the center workspace area. Use the address bar to navigate, move backward and forward through page history, reload the current page, or open the current URL in your external browser if you want to leave Nora. ## How automatic browsing works Nora can also open a new internal browser tab automatically when a workspace terminal detects a new local URL. Turn that on when you frequently start local dev servers and want previews to appear immediately without copying links around by hand. ## How local port detection works When a terminal session outputs a local URL or port, Nora can detect it and attach that information to the session. You will see the detected port in the session header, and if Nora has the full local URL it can give you a one-click way to open that app. This is especially useful for dev servers, local dashboards, and preview environments that come up during normal work. --- # Screenshots Source: https://www.withnora.run/docs/screenshots Paste image attachments directly into agent input so terminal-based agents can work from visual context as well as text. ## What screenshot support does Screenshot support lets you send visual context directly to an agent session. Instead of describing a layout bug or broken state from memory, you can attach the image to the same instruction you are sending to the agent. ## How to use it Click into the focused agent input, paste an image from your clipboard, confirm that the attachment appears, and remove any images you do not want to send. You can also preview an attachment before submitting. When you send the instruction, the screenshot goes with it as part of the same agent input. ## When to use screenshots Use screenshot attachments when the bug, design issue, or visual state is easier to understand from an image than from text alone. This is especially useful for UI regressions, layout problems, and any workflow where the agent needs to inspect what happened on screen. --- # Remote repos Source: https://www.withnora.run/docs/remote Open repositories either through an SSH mount or directly over SSH, and keep remote sessions visible alongside local work. ## What remote support does Nora supports two remote access modes for SSH-based projects. You can mount a remote path and work with it like a local folder, or you can open the repository directly over SSH so Git, agents, and terminals stay on the server without creating a local mount. ## How to connect a remote repo Use the add-workspace flow and choose the remote-over-SSH option. Then choose the connection mode that fits the job. Pick mount mode when you want a mounted path you can browse like a local folder. Pick direct SSH mode when you want the repository to stay remote and you want Git, terminals, and agent work to run on the server itself. In both cases, once connected, the remote project behaves like a normal Nora workspace. > Warning: Mounted workspaces can feel slower > > Mounted SSH workspaces may be slower than direct SSH sessions because SSH file systems add network latency and usually have weaker filesystem performance than a local disk. If browsing a mounted repo feels sluggish, prefer direct SSH mode so the work stays on the server. ## How to manage remote environments Use the remote mounts section in the workspace sidebar to inspect active mounts, revisit their remote paths, and unmount them when they are no longer needed. If you are using direct SSH mode, there is no mount to clean up because the workspace stays remote by design. If Nora cannot find remote mount support on the machine, it can still fall back to direct SSH when that mode is available. --- # Integrations Source: https://www.withnora.run/docs/integrations Tie the workspace into repository hosting and deployment systems so review and release workflows stay close to the active worktree. ## What integrations are present Nora connects the workspace to GitHub, GitLab, and Vercel so code review and deployment tasks do not have to happen in a separate tool at the end of the process. ## How to use source control integrations After an agent or terminal produces changes in a branch, open the review flow and create a pull request or merge request from the current branch against the desired base branch. Nora validates the branch selection before submission so you do not accidentally open a request against the same source branch. ## How to use Vercel integration Connect a Vercel account in settings, store a token, link the current workspace to a Vercel project, and then use the Vercel panel to inspect deployments or trigger redeploys. The integration is designed to keep deployment context attached to the same workspace that produced the code changes. --- # Operator control Source: https://www.withnora.run/docs/approvals Nora keeps high-impact actions operator-driven by exposing branch targets, access modes, diffs, and launch decisions before work proceeds. ## What operator control means here The current app does not hide repository actions behind silent automation. You choose whether a session is read-only or write-enabled, select the target checkout explicitly, inspect terminal output live, and review changed files and diffs before deciding what should happen next. ## How to use it in practice Use read-only mode for exploration, use write mode only when the session should edit, and prefer new worktrees for risky or parallel tasks. After a run, open the changes panel and inspect the diff before creating a pull request, merging a branch, or asking another session to continue. ## Where the review checkpoints live The review checkpoints are the launch dialog, the focused terminal panel, and the changes panel. Together they tell you what command is running, where it is running, and what files changed, which is enough to keep the operator in control of the workflow even before a richer approval system exists.