Guide

Claude Code + NOAN, from zero

Never opened a terminal in anger? This walkthrough takes you from nothing to an agent grounded in your company's verified facts: install Claude Code, sign in, connect the NOAN API, and add the NOAN skill. About fifteen minutes end to end.

Start free trial About the API

Part 1

Set up Claude Code

Claude Code is Anthropic's agent that runs in your terminal: you talk to it in plain language and it reads, writes, and runs things on your machine, asking permission as it goes.

What you need before you start

A computer running macOS 13 or newer, Windows 10 or newer, or a mainstream Linux, with an internet connection. No programming knowledge is required.

You also need a Claude account. The simplest route is a Claude Pro subscription (currently from $20 a month at claude.com/pricing), which includes Claude Code with no extra setup. Developers can instead use an Anthropic Console account with pay-as-you-go API billing, but for a first run the subscription is easier: you will sign in with your normal Claude login and never touch an Anthropic key.

Install Claude Code

Open your terminal (on a Mac: press Cmd+Space, type Terminal, press Enter. On Windows: open the Start menu and type PowerShell). Then paste the one line for your system and press Enter.

macOS and Linux

curl -fsSL https://claude.ai/install.sh | bash

Windows (PowerShell)

irm https://claude.ai/install.ps1 | iex

The installer is self-contained and keeps itself up to date. If you already use Node.js and prefer npm, npm install -g @anthropic-ai/claude-code works too (Node 22 or newer). On Windows, installing Git for Windows alongside is recommended so Claude Code can run shell commands.

Create a folder for it to work in

Here is the part nobody tells you: Claude Code always works inside one folder on your computer, called its workspace. That folder is how it works: it can read the files in there, edit them, and create new ones, and it will ask your permission before it does. It cannot touch anything outside that folder unless you allow it, so the folder is both its desk and its fence.

So before you start it, make a folder. Any of these ways works: on a Mac, open Finder, go to your Documents, and choose File, then New Folder, and name it something like noan-workspace. On Windows, open File Explorer, go to Documents, right-click, New, Folder. Or create it straight from the terminal:

Make a folder from the terminal

mkdir noan-workspace

It starts empty, and that is fine. As you work, Claude Code will fill it with the things you make together.

Start it and sign in

In the terminal, move into your new folder with the cd command (short for change directory), then start Claude Code:

First launch

cd noan-workspace
claude

On first run your browser opens a sign-in page. Choose your Claude account (the Pro subscription login) or your Console account if you set one up instead. When the browser says you are signed in, return to the terminal: it will say Login successful, then drop you at a prompt asking what you would like to do. If the browser does not open by itself, the terminal shows a key to press to copy the sign-in link.

Check it works

Two quick checks, either run from the terminal (outside a session):

Verify the install

claude --version
claude doctor

The first prints a version number; the second runs a health check over the install, settings, and connections and tells you if anything needs fixing.

Learn the three basics

First, talk to it naturally: type what you want, in full sentences, and press Enter. Second, Claude Code asks permission before it edits files or runs commands: read what it proposes and answer yes or no (you can loosen or tighten this later with Shift+Tab, which cycles permission modes). Third, to leave, type /exit. That is genuinely all you need for this guide.

One more thing worth knowing: once this setup is done, the terminal is not the only door. The Claude desktop app on Mac and Windows includes Claude Code too, so you can open the same workspaces, with the same account and the same skills, from a friendlier window whenever you prefer it to the terminal.

Part 2

Connect the NOAN API

Two things connect Claude Code to your fact base: an API key that says who you are, and the API docs that tell it what it can do.

Create your NOAN API key

In your NOAN workspace at app.getnoan.com, go to Settings, then API, then New key. The key is personal: it acts as you and can never see more than your role and fact permissions allow. Every plan includes unlimited keys, so make one just for Claude Code. Copy it now; treat it like a password.

Give the key to Claude Code, safely

Never paste the key into the chat itself. Instead, set it as an environment variable in the terminal before you start Claude Code, so its tools can use it without the key ever appearing in the conversation.

macOS and Linux

export NOAN_API_KEY="paste-your-key-here"
claude

Windows (PowerShell)

$env:NOAN_API_KEY = "paste-your-key-here"
claude

That lasts for the current terminal window. To make it permanent, add the same variable to the env block of ~/.claude/settings.json, and Claude Code will load it in every session.

Test the connection

Inside Claude Code, ask it to verify the connection in plain language, for example: "Use the NOAN_API_KEY environment variable to call https://api.getnoan.com/v1/me and tell me which project and identity the key belongs to." Approve the command it proposes. A healthy reply names your project and your identity. Under the hood it runs exactly this:

What Claude Code runs

curl -s https://api.getnoan.com/v1/me \
  -H "Authorization: Bearer $NOAN_API_KEY"

Hand it the API docs

The whole API is described at one public URL. Paste this prompt into Claude Code and it will learn the full surface, then be able to read facts, contacts, and tasks, and write back, all with your approval:

Paste into Claude Code

Read the NOAN API docs: https://api.getnoan.com/openapi.json

I have a NOAN workspace and my key is in the NOAN_API_KEY environment
variable. Read our verified facts and give me a one-paragraph summary
of what my company's fact base contains.

Part 3

Add the NOAN skill

A skill is a markdown file Claude Code reads to learn a workflow. NOAN publishes one that teaches it the fact layer properly: ground answers in facts first, read freely, and always ask before writing.

Install NOAN's skill (recommended)

Inside Claude Code, run these two commands:

In Claude Code

/plugin marketplace add getnoan/skills
/plugin install noan@noan-skills

Prefer doing it from the terminal? Either of these works too:

Universal installer (any agent)

npx skills add getnoan/skills

Manual copy

git clone https://github.com/getnoan/skills /tmp/noan-skills
mkdir -p ~/.claude/skills
cp -r /tmp/noan-skills/skills/noan-fact-layer ~/.claude/skills/

From the next session on, Claude Code triggers the skill whenever a task touches NOAN or your company truth: it reads facts before answering, never invents what is not in the fact base, and asks for explicit confirmation before any write. The skill source is public at github.com/getnoan/skills and readable at getnoan.com/skill.md.

Or write your own

A skill is a folder containing a SKILL.md file. Put it in ~/.claude/skills/ to use it everywhere, or in a project's .claude/skills/ for that project only. A minimal NOAN skill of your own looks like this:

~/.claude/skills/my-noan/SKILL.md

---
description: "Ground answers in our NOAN facts before answering
  company questions. Read freely; confirm before writing."
---

# Our fact layer

- API spec: https://api.getnoan.com/openapi.json
- Auth: Bearer token from the NOAN_API_KEY environment variable
- Before answering anything about our company, GET the relevant
  facts and answer from them. If a fact is missing, say so.
- Ask for explicit confirmation before any POST, PATCH, or PUT.

The description tells Claude Code when to load it automatically; the body is the instruction it follows. Start from NOAN's published skill and trim or extend it for your own conventions.

Try it

Three first prompts that prove the loop works, in increasing ambition:

Starter prompts

What does our fact base say about our pricing?

Create a NOAN task titled "Review Q3 positioning" in the backlog.

Draft a short intro email about our product for a prospect,
grounded only in our verified facts.

The first is a pure read. The second is a write, so expect Claude Code to show you the task and ask before creating it. The third is the point of all of this: output built from your company's truth instead of a guess.

Fifteen minutes to a grounded agent

Every NOAN plan includes the API, MCP, and unlimited keys. Set up your fact base, connect Claude Code, and everything it makes for you is true.

Start free trial Build a full agent