💡 To print or save as PDF: press Ctrl+P in your browser → choose "Save as PDF"
BrainCell AI Agent
User Manual
Step-by-step guide to using Claude Code with BrainCell
1. What Is the BrainCell AI Agent?
The BrainCell AI Agent is Claude Code — an AI-powered coding assistant that runs in your terminal and has full access to your BrainCell repository. Unlike a regular chatbot, it can read, understand, and modify your actual files.
| Feature | Description |
|---|
| Reads your code | Automatically finds and reads MOD, HOC, and Python files |
| Understands biophysics | Explains KINETIC schemes, ion channels, transporters in scientific detail |
| Suggests modifications | Proposes code changes — you approve before anything is saved |
| No extra cost | Runs on your Claude Pro subscription (£18/month) |
| Remembers context | Within a session, remembers which files it has already read |
⚠️ Important: Claude Code can read and edit your files. Always review proposed changes before approving.
Use Git to back up your work before asking Claude Code to modify files.
2. Starting the Agent — Every Time
Follow these steps each time you want to use the agent.
Click Start Menu → search Anaconda Prompt → click to open.
You will see a black window with a prompt like: (base) C:\Users\savtc>
2
Navigate to your BrainCell repository
Type the following command and press Enter:
cd D:\GitHubRusakovLab\BrainCellClaude
The prompt will change to: (base) D:\GitHubRusakovLab\BrainCellClaude>
Type the following and press Enter:
claude
You will see the Claude Code welcome screen with your name and account details.
4
Trust the folder (first time only)
The very first time, Claude Code asks if you trust the folder. Select 1 and press Enter:
Quick safety check: Is this a project you created or one you trust?
> 1. Yes, I trust this folder
2. No, exit
5
Allow file reading for the session
When Claude Code first tries to read a file, select option 2 to allow access for the whole session — no more prompts:
Do you want to proceed?
1. Yes
> 2. Yes, allow reading from BrainCellClaude/ during this session <-- select this
3. No
✔ You are ready! Type your question at the > prompt and press Enter.
3. Asking Questions About BrainCell
Type any question in plain English. Claude Code will find the relevant files and answer based on your actual code.
3.1 Understanding MOD files (biophysics)
> How does GluTrans.mod work? Explain the biophysics.
> What is the kinetic scheme in cadifus.mod?
> Explain the voltage dependence in Kir4.mod
> What ions does nkpump.mod use and what does it model?
> Explain all the states in the GluTrans transport cycle
> What is the rate-limiting step in the glutamate transporter cycle?
3.2 Searching across the codebase
> Find all mechanisms that handle calcium diffusion in astrocytes
> Which MOD files use KINETIC blocks?
> What mechanisms are involved in extracellular K+ dynamics?
> Find all gap junction mechanisms and explain their differences
> Which Python files generate HOC code?
> What files are involved in simulating a myelinated axon?
3.3 Understanding architecture
> Explain the architecture of the _Code/Managers/ folder
> How does SimMyelinatedAxon.py work?
> What does CommonLoads.hoc load and why is it important?
> How do the JSON files in Biophysics/ connect to the HOC files?
> What is the role of GeneratorsForMainHocFile.py?
3.4 Comparing files
> Compare Kir.mod and Kir4.mod — what are the differences?
> What is the difference between gap.mod and gap_neuron.mod?
> Compare GAT1_Bicho.mod and GAT1_current.mod
> How does na3n.mod differ from naxn.mod?
3.5 Physiological interpretation
> What would happen to glutamate clearance if I doubled k61 in GluTrans.mod?
> How would increasing the Kir4.1 density affect K+ buffering in the astrocyte?
> What are the limitations of the current cadifus.mod model?
> Suggest improvements to make GluTrans.mod more realistic
💡 Tip: Be specific for better answers.
Instead of: "explain calcium"
Ask: "How does cadifus.mod model IP3-dependent calcium release in astrocytes?"
4. Modifying Files Safely
⚠️ Safety Rule: Before modifying any file, commit your current work in Git first.
This gives you a safe restore point if something goes wrong.
4.1 How to request a modification
Describe what you want in plain English, mentioning the file name:
> Add Q10 temperature dependence (Q10=2.2) to Kir4.mod
> In GluTrans.mod, make the transporter density a RANGE variable
> Add a comment block to cadifus.mod explaining the IP3 kinetics
> In nkpump.mod, add a RANGE variable to expose the pump current for recording
> Add a RANGE variable itrans to GluTrans.mod so the current can be plotted
4.2 The safe modification workflow
- Claude Code reads the file and proposes a change
- It shows you exactly what it plans to write
- It asks: "Do you want to proceed? 1. Yes / 2. No"
- Read the proposed change carefully before selecting Yes
- If you select Yes, the file is saved immediately
- Test by recompiling MOD files and running your simulation
4.3 What to check before approving a MOD change
- USEION declarations match all ions that are read or written
- RANGE variables declared for any new parameters you want to access from HOC
- Units are correct: conductances in S/cm², currents in mA/cm², concentrations in mM, time in ms
- STATE variables have initial values in the INITIAL block
- New parameters have sensible default values
4.4 Undoing a change
If something goes wrong, restore the original file from Git (in a separate Anaconda Prompt window):
cd D:\GitHubRusakovLab\BrainCellClaude
git checkout Mechanisms/Common/MOD_files/GluTrans.mod
5. Example Questions — Ready to Use
Copy and paste any of these directly into the Claude Code prompt.
5.1 Biophysics analysis
| Question | What you will learn |
|---|
| How does GluTrans.mod model glutamate uptake into astrocytes? | 6-state Markov cycle, voltage dependence, electrogenic current formula |
| Explain the IP3-calcium coupling in cadifus.mod | IP3 receptor kinetics, calcium diffusion, buffering mechanisms |
| What is the physiological role of Kir4.1 and how is it modelled in Kir4.mod? | K⁺ spatial buffering, Kir4.1 channel properties, current formula |
| How does nkpump.mod respond to intracellular Na⁺? | Pump stoichiometry, concentration dependence, voltage sensitivity |
| What is the difference between gap40tau, gap43tau, and gap45tau? | Tau values, intended use cases, parameter differences |
| Explain all mechanisms involved in GABA signalling in BrainCell | GAT1 transporter, GABA_tonic, GabaUpdate — roles and interactions |
5.2 Architecture questions
| Question | What you will learn |
|---|
| What does GeneratorsForMainHocFile.py generate and when is it called? | HOC code generation pipeline |
| How does InsideOutDiffCalculator.py implement intracellular diffusion? | Diffusion algorithm, compartment coupling |
| Explain the relationship between SynManager.hoc and AMPASyn.mod | How the manager assigns mechanisms to compartments |
| What does LFPCalculator.py compute and how? | Local field potential algorithm, electrode geometry |
5.3 Modification requests
| Request | Expected result |
|---|
| Add Q10 temperature correction (Q10=3) to GluTrans.mod | New Q10 parameter, all rates multiplied by Q10^((T−T₀)/10) |
| Add a comment header to Kir4.mod explaining its physiological role | Documentation block at top of file |
| In cadifus.mod, make the diffusion coefficient DCa a RANGE variable | DCa moved from PARAMETER to RANGE, accessible from HOC |
| Add a RANGE variable itrans to GluTrans.mod so the current can be plotted | RANGE declaration added, itrans assigned in BREAKPOINT block |
6. Tips, Shortcuts and Troubleshooting
6.1 Keyboard shortcuts inside Claude Code
| Key / Command | Action |
|---|
Ctrl + C | Cancel the current operation |
Ctrl + L | Clear the screen |
/exit | Quit Claude Code |
/help | Show all available commands |
Ctrl + O | Expand collapsed file list — see which files are being read |
| ↑ Up arrow | Recall previous command |
6.2 Tips for better answers
- Mention the file name when you know it
- Add biological context: "in the context of astrocyte calcium signalling"
- Ask follow-up questions: "Can you show me where exactly in the code that happens?"
- Ask for physiological interpretation: "What would doubling k61 do to glutamate clearance speed?"
- If the answer seems wrong, say: "Please re-read the file and try again"
6.3 Session management
- At the start of each session, allow folder reading when prompted (select option 2)
- Claude Code does not remember previous sessions — start fresh each time
- For complex tasks, break them into steps: understand first, then modify
- If Claude Code seems confused, start a new session: type
/exit then claude
6.4 Troubleshooting
| Problem | Solution |
|---|
claude is not recognised as a command | Close and reopen Anaconda Prompt, then type: claude |
| Claude Code gives a wrong answer about a file | Ask: "Please re-read the file and try again" |
| "credit balance too low" error | Run claude again and choose No when asked about the API key — this uses your Pro account instead |
| Modified file causes NEURON compilation error | Restore with: git checkout <filepath> |
| Very slow response (>1 minute) | Normal for complex questions. Press Ctrl+O to see which files are being read |
| Claude Code asks for folder trust every session | Make sure you cd into D:\GitHubRusakovLab\BrainCellClaude before typing claude |
7. Quick Reference Card
Print this page and keep it at your desk.
START EVERY SESSION:
1. Open Anaconda Prompt
2. cd D:\GitHubRusakovLab\BrainCellClaude
3. claude
4. When asked about file reading → select option 2 (allow for session)
ANALYSIS — safe, read only:
How does [filename].mod work?
Explain the biophysics of [mechanism]
Find all files related to [topic]
Compare [file1] and [file2]
What would changing [parameter] do physiologically?
MODIFICATION — always review before approving!
Add [parameter] to [filename].mod
Make [variable] a RANGE variable in [filename].mod
Add temperature dependence Q10=[value] to [filename].mod
Add comments explaining [concept] to [filename]
EXIT: type /exit or press Ctrl+C
UNDO A FILE CHANGE:
git checkout Mechanisms/path/to/filename.mod
Savtchenko / Rusakov Lab, UCL • BrainCell AI Agent User Manual • February 2026