💡 To save as PDF: press Ctrl+P → Save as PDF

BrainCell AI Agent

Complete Setup & User Manual

From zero to working AI agent — step by step

Files you received: braincell_mapper.py & braincell_agent.py

Requirements: Python (Anaconda), Anthropic API key

Estimated setup time: 20–30 minutes

Running cost: ~$5–20 / month (Anthropic API)

Overview — What You Are Setting Up

You have received two Python scripts that together create an AI assistant for the BrainCell NEURON codebase. Here is what each file does:

File	What it does	When to run
`braincell_mapper.py`	Scans all MOD, HOC, and Python files in your repository and creates a braincell_map.json index file	Once at the start, and again whenever you add new files to the repository
`braincell_agent.py`	The AI agent — reads your code and answers questions about biophysics, architecture, and can propose modifications	Every time you want to use the agent

Setup sequence:
Step 1: Install Anaconda → Step 2: Get API key → Step 3: Install anthropic package → Step 4: Edit the two files → Step 5: Run mapper → Step 6: Run agent → Ask questions!

1. Prerequisites — What You Need First

1.1 Python (Anaconda) — if not already installed

Download Anaconda

Go to anaconda.com/download and download the installer for Windows. Run it and accept all defaults.

Verify installation

Open Anaconda Prompt from the Start Menu and type:

python --version

You should see something like: Python 3.11.x. If so, Anaconda is working.

1.2 Check where Anaconda is installed

In Anaconda Prompt, type:

where python

Note the path that appears — it will look like one of these:

C:\Users\YourName\anaconda3\python.exe
C:\ProgramData\Anaconda3\python.exe

You will need this path in Step 4 if using Spyder.

2. Place the Files in the Right Location

Find your BrainCell repository folder

This is the folder that contains your MOD, HOC, and Python files. For example: D:\MyWork\BrainCell\

Copy both files into that folder

Place braincell_mapper.py and braincell_agent.py directly in the root of your BrainCell folder.

Your folder should now look like this:

D:\MyWork\BrainCell\
  ├── braincell_mapper.py       <-- you just added this
  ├── braincell_agent.py        <-- you just added this
  ├── Mechanisms\
  │     ├── Astrocyte\MOD_files\
  │     ├── Neuron\MOD_files\
  │     └── Common\MOD_files\
  ├── _Code\
  ├── Geometry\
  └── ...other folders...

Edit the repository path in braincell_mapper.py

Open braincell_mapper.py in any text editor (Notepad is fine). Find line 8 and change the path to match YOUR folder:

# BEFORE (example — change this to your actual path):
REPO = Path(r"C:\Leonid\GitHub\XiaolanWu\BrainCell")

# AFTER (your actual path):
REPO = Path(r"D:\MyWork\BrainCell")

Edit the repository path in braincell_agent.py

Open braincell_agent.py in any text editor. Find line with REPO = Path(... and change it to the same path:

# Change this to YOUR actual BrainCell folder path:
REPO = Path(r"D:\MyWork\BrainCell")

⚠️ Important: Use a lowercase r before the quote marks: r"D:\MyWork\BrainCell"
This tells Python to treat backslashes as literal characters, not escape sequences.

3. Get Your Anthropic API Key

The AI agent uses the Anthropic API (Claude AI). You need an account and API key to use it.

Create an Anthropic account

Go to console.anthropic.com and sign up (or sign in if you already have an account).

Get your API key

In the left sidebar, click API Keys → click Create Key → give it a name (e.g. "BrainCell") → copy the key.

Your key will look like this:

sk-ant-api03-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

🔴 Security warning: Never share your API key with anyone. Never paste it into chat messages, emails, or public documents. If you accidentally expose it, go to console.anthropic.com immediately and delete it, then create a new one.

Add credits to your account

In the Console, click Billing → Add credits. Add $10 to start — this lasts weeks of normal use.

Usage level	Approximate cost	Typical use
$5	~100–200 questions	Getting started
$10	~300–500 questions	Active research
$20/month	~600–1000 questions	Daily use

Save the API key permanently on your Windows computer

Open Anaconda Prompt and run this command (replace with your actual key):

setx ANTHROPIC_API_KEY "sk-ant-api03-YOUR_ACTUAL_KEY_HERE"

You should see: SUCCESS: Specified value was saved.

Close and reopen Anaconda Prompt — the key is now saved permanently and will be found automatically every time.

✔ Verify it saved correctly — in a new Anaconda Prompt window type:
echo %ANTHROPIC_API_KEY%
It should print your key starting with sk-ant-...

4. Install the Anthropic Python Package

The agent needs the anthropic Python package. Install it once:

Open Anaconda Prompt

From Start Menu → search "Anaconda Prompt" → click to open.

Install the package

Type this command and press Enter:

pip install anthropic

You will see packages downloading and installing. Wait for it to finish.

Verify installation

Type:

python -c "import anthropic; print(anthropic.__version__)"

You should see a version number like 0.40.0. If so, the package is installed correctly.

⚠️ If you use Spyder IDE: Spyder may have its own Python that is separate from Anaconda. If you get ModuleNotFoundError: No module named 'anthropic' when running from Spyder, go to:

Tools → Preferences → Python interpreter
Select "Use the following interpreter"
Enter your Anaconda Python path, for example: C:\Users\YourName\anaconda3\python.exe
Click OK → restart the kernel → run the install command again.

5. Run the Mapper — Create the Repository Index

The mapper scans your BrainCell repository and creates a braincell_map.json file that the agent uses to find relevant files quickly.

Open Anaconda Prompt and navigate to your BrainCell folder

Replace the path below with your actual BrainCell folder:

cd D:\MyWork\BrainCell

Run the mapper

Type:

python braincell_mapper.py

You will see output like this:

Scanning BrainCell repository...
==================================================
  BRAINCELL REPOSITORY MAP
==================================================
  MOD files:    131
  HOC files:    346
  Python files: 74

  Ion channels by ion type:
    k           : 53 mechanisms
    ca          : 27 mechanisms
    na          : 24 mechanisms
    ...

  Map saved to: D:\MyWork\BrainCell\braincell_map.json

✔ A file called braincell_map.json now exists in your BrainCell folder. The agent is ready to use.

Run the mapper again any time you add new MOD or Python files to the repository.

6. Run the Agent and Ask Questions

Open Anaconda Prompt and navigate to your BrainCell folder

cd D:\MyWork\BrainCell

Run the agent

python braincell_agent.py

You will see the welcome message:

============================================================
  BrainCell AI Agent
  Repository: D:\MyWork\BrainCell
  Index: 131 MOD  346 HOC  74 PY
============================================================
Type "help" for available commands, "exit" to quit.

>

Type your first question at the > prompt and press Enter

> How does GluTrans.mod work? Explain the biophysics.

The agent will find the file, read it, and give you a detailed biophysical explanation. Wait 20–60 seconds for a response.

7. Agent Commands and Usage

Command	What it does	Example
Just type a question	Ask anything — agent searches for relevant files automatically	`How does cadifus.mod model calcium diffusion?`
`ask <question>`	Same as above — the "ask" prefix is optional	`ask What is the role of the Na/K pump?`
`search <keyword>`	Find all files related to a keyword	`search calcium gap junction`
`explain <filepath>`	Full biophysical explanation of one specific file	`explain Mechanisms/Common/MOD_files/GluTrans.mod`
`modify <filepath> <instruction>`	Ask the agent to modify a file — shows preview, asks your approval before saving	`modify Mechanisms/Astrocyte/MOD_files/Kir4.mod Add Q10 temperature dependence`
`help`	Show all commands	`help`
`exit`	Quit the agent	`exit`

Example questions to get started

> How does GluTrans.mod work? Explain the biophysics.
> What mechanisms handle calcium dynamics in astrocytes?
> Find all MOD files that use KINETIC blocks
> Compare Kir.mod and Kir4.mod — what are the differences?
> Explain the architecture of the _Code/Managers/ folder
> search extracellular potassium
> explain Mechanisms/Neuron/MOD_files/AMPASyn.mod

8. Modifying Files Safely

⚠️ Before modifying any file: make sure your work is committed in Git so you can restore the original if needed.

8.1 How to request a modification

> modify Mechanisms/Astrocyte/MOD_files/Kir4.mod  Add Q10 temperature dependence (Q10=2.2)
> modify Mechanisms/Common/MOD_files/GluTrans.mod  Make the transporter density a RANGE variable
> modify Mechanisms/Common/MOD_files/cadifus.mod  Add a comment header explaining the IP3 kinetics

8.2 The approval workflow

The agent reads the file
It writes a modified version and shows you a preview
It asks: "Save changes? (y/n):"
Read the preview carefully before typing y
Type y to save, or n to cancel

8.3 Undoing a change

If the modified file causes problems, restore the original from Git:

cd D:\MyWork\BrainCell
git checkout Mechanisms/Common/MOD_files/GluTrans.mod

9. Troubleshooting

Error message	Cause	Solution
`ModuleNotFoundError: No module named 'anthropic'`	Package not installed in the Python that is running the script	Run `pip install anthropic` in Anaconda Prompt. If using Spyder, change the Python interpreter to Anaconda (see Section 4).
`AuthenticationError` or `Could not resolve authentication method`	API key not found	Run `setx ANTHROPIC_API_KEY "sk-ant-..."` in Anaconda Prompt, then close and reopen the prompt.
`FileNotFoundError: braincell_map.json not found`	Mapper has not been run yet	Run `python braincell_mapper.py` first.
`credit balance too low`	No credits in your Anthropic account	Go to console.anthropic.com → Billing → Add credits.
`REPO path not found` or files not being found	Wrong path set in the script	Open the script and check the `REPO = Path(r"...")` line. Make sure it matches your actual folder path exactly.
Agent gives wrong answer about a file	May have read wrong version	Ask: "Please re-read the file and try again"
Very slow response (>60 seconds)	Complex question, many files being read	Normal behaviour — wait for it to finish.

10. Quick Reference — Print This Page

FIRST TIME SETUP (do once):
1. Install Anaconda from anaconda.com/download
2. Go to console.anthropic.com → create account → API Keys → Create Key → copy it
3. Add billing credits at console.anthropic.com → Billing
4. In Anaconda Prompt: setx ANTHROPIC_API_KEY "sk-ant-YOUR_KEY"
5. In Anaconda Prompt: pip install anthropic
6. Copy both .py files into your BrainCell folder
7. Edit REPO = Path(r"...") in both files to your BrainCell folder path
8. In Anaconda Prompt: cd D:\YourPath\BrainCell then python braincell_mapper.py

EVERY SESSION:
1. Open Anaconda Prompt
2. cd D:\YourPath\BrainCell
3. python braincell_agent.py
4. Type your question at the > prompt

USEFUL COMMANDS:
search <keyword>                        Find relevant files
explain Mechanisms/.../file.mod Full explanation of one file
modify Mechanisms/.../file.mod task Propose a modification
help                                      Show all commands
exit                                      Quit the agent

SAFETY:
• Never share your API key
• Always commit in Git before modifying files
• Always review the proposed change before typing y to save
• To undo: git checkout path/to/filename.mod

BrainCell AI Agent • Complete Setup & User Manual • Savtchenko / Rusakov Lab, UCL • 2026