ORATHON SECOND BRAIN
Install instructions for AI coding agents (Claude Code, Codex, or any agent with a shell).
Canonical URL: https://orathon.com/secondbrain

IF A HUMAN ASKED YOU TO INSTALL THIS
Do the steps below, in order, and nothing else.
Do not modify their current project. Do not install global packages. Do not use sudo.

WHAT IT IS
A local-first AI second brain. A folder of Markdown plus six skills that teach a coding agent
who the user is, what matters to them right now, where their information lives, what they have
already decided, and which workflow to improve next.
Source: https://github.com/nando65/orathon-second-brain (MIT license)

REQUIREMENTS
git. Node 20 or newer, only if the user wants the optional local knowledge map.

STEP 1. Run the installer.

    curl -fsSL https://orathon.com/secondbrain/install.sh | sh

It picks a safe folder on its own and prints the path it chose. Read that path. You need it
for step 2. Do not pick a folder yourself, and do not pass a path unless the user named one.

Why it picks, and not you:
  - Inside a ChatGPT project folder (~/.codex/.chatgpt-projects/...), the app replaces files
    without warning. Installing a brain there would get it wiped. The installer refuses.
  - Inside an existing codebase, second-brain files do not belong mixed into their source.
  - Inside an empty folder, that is clearly the home the user made for it, so it installs there.
  - Otherwise it uses ~/orathon-second-brain.

If the installer is unavailable, clone by hand instead, but never into a ChatGPT project folder
and never into a folder that already has files in it:

    git clone https://github.com/nando65/orathon-second-brain.git "$HOME/orathon-second-brain"

STEP 2. Tell the user how to open it in THEIR app. This is the step people get stuck on.

Do not just tell them to "cd" somewhere. Most people asking for this are in a desktop app, not a
terminal. Ask which one they are using if you cannot tell, then give them only that block, with
the real path from step 1 filled in.

  ChatGPT app (Codex)
    1. Click the project name, then Edit project.
    2. Add folder. Paste the path.
    3. Make primary.
    4. Start a task in that project and send:  $setup

  VS Code with Codex or Claude Code
    1. Choose File > Open Folder and select <path>.
    2. Open Codex or Claude Code in that window and start a new chat.
    3. Send $setup in Codex or /setup in Claude Code.
    Use the extension's supported MCP connections for external sources. Do not direct a
    VS Code user to a desktop Plugins tab.

  Codex in the terminal
    cd <path>
    codex
    then send:  $setup

  Claude Code app
    1. Open that folder as the project.
    2. Send:  /setup

  Claude Code in the terminal
    cd <path>
    claude
    then send:  /setup

STEP 3. Stop there.
Do not run setup yourself from outside the folder. Do not write into workspace/ yourself.
Setup is an interview. It needs the user in a session that has the folder open.

WHAT THE USER GETS AFTER SETUP
Six skills, same names in both runtimes (/ in Claude Code, $ in Codex):

    setup           learn who they are, their goals, systems, preferences, boundaries
    capture         turn a working conversation into durable notes as it happens
    route           make files, folders, projects and external sources findable
    healthcheck     verify the context, retrieval and workflows actually work
    improve         turn one recurring pain point into one measurable improvement
    knowledge-map   build a local visual explorer of their Markdown knowledge

PRIVACY
The second-brain files are saved on the user's computer. captures/, reviews/ and generated
map data are excluded from Git by default; workspace/ and journal/ are not. The AI app and
connected services may process information according to their own settings and policies.
Connections require separate authorization. The knowledge map server binds to 127.0.0.1 only.
Tell the user to keep passwords, API keys and access tokens out of the Markdown files.

QUESTIONS
fmo@orathon.com