The terminal emulates a 1970s hardware device that read keystrokes as a stream. Each line you type
gets consumed when you press Enter and becomes read-only history.
Only the current command line is editable.
That's why you can't click into past output and edit it — you're not in a document. You're in a stream.
On macOS Terminal you can mouse-select text to copy it with{" "}
⌘C, but you can't move your typing cursor with a click. The cursor lives on the
active input line and is driven by keyboard only.
The three layers
Scrollback
Past output. Read-only. Selectable to copy, not editable.
Prompt line
The line you're typing on right now. The only editable region. Keyboard-driven.
Running process
When a command is running, the prompt is gone — output streams until the program exits.
iTerm2 (free Terminal replacement) supports click-to-position the cursor when shell integration is enabled.
Worth installing if mouse-free editing keeps slowing you down. Most macOS devs use iTerm2 over Terminal.app.
);
};
// ============================================================
// EDITING SECTION — interactive cursor demo
// ============================================================
const EditingSection = () => {
const accent = ACCENTS.editing;
const initial = "cd /Users/druemclean/projects/options-edge";
const [text, setText] = useState(initial);
const [cursor, setCursor] = useState(initial.length);
const [lastAction, setLastAction] = useState("Cursor at end of line");
const reset = () => { setText(initial); setCursor(initial.length); setLastAction("Reset"); };
const wordLeft = () => {
let i = cursor - 1;
while (i > 0 && text[i] === " ") i--;
while (i > 0 && text[i - 1] !== " " && text[i - 1] !== "/") i--;
setCursor(Math.max(0, i)); setLastAction("⌥ ← jumped one word back");
};
const wordRight = () => {
let i = cursor;
while (i < text.length && (text[i] === " " || text[i] === "/")) i++;
while (i < text.length && text[i] !== " " && text[i] !== "/") i++;
setCursor(Math.min(text.length, i)); setLastAction("⌥ → jumped one word forward");
};
const lineStart = () => { setCursor(0); setLastAction("⌃A jumped to start of line"); };
const lineEnd = () => { setCursor(text.length); setLastAction("⌃E jumped to end of line"); };
const killBefore = () => {
setText(text.slice(cursor)); setLastAction(`⌃U deleted everything before cursor`);
setCursor(0);
};
const killAfter = () => {
setText(text.slice(0, cursor)); setLastAction(`⌃K deleted everything after cursor`);
};
const deleteWord = () => {
let i = cursor - 1;
while (i > 0 && text[i] === " ") i--;
while (i > 0 && text[i - 1] !== " " && text[i - 1] !== "/") i--;
const removed = text.slice(i, cursor);
setText(text.slice(0, i) + text.slice(cursor));
setCursor(i); setLastAction(`⌥ Delete removed "${removed}"`);
};
const buttons = [
{ label: "⌥ ←", title: "Word left", fn: wordLeft },
{ label: "⌥ →", title: "Word right", fn: wordRight },
{ label: "⌃ A", title: "Line start", fn: lineStart },
{ label: "⌃ E", title: "Line end", fn: lineEnd },
{ label: "⌥ Delete", title: "Delete word back", fn: deleteWord },
{ label: "⌃ U", title: "Kill before cursor", fn: killBefore },
{ label: "⌃ K", title: "Kill after cursor", fn: killAfter },
];
return (
These shortcuts replace what you'd normally do with a mouse. Click each one to see what it does.
The cursor (the orange block) moves; deletions actually change the line.
⌥ ← / ⌥ → word-jump replaces the slow character-by-character travel.{" "}
⌃ A / ⌃ E line-jump.{" "}
⌃ U nukes the line so you can retype.{" "}
⌥ Delete deletes the word you just typed wrong.
Everything else is optional.
"Where am I right now?" Prints your current directory.
ls
List what's in this folder. Add -la for hidden files + details.
cd folder
Go into folder. Hit Tab mid-word to autocomplete.
cd ..
Go up one level.
cd ~
Jump to your home folder (/Users/druemclean).
cd -
Go back to where you just were. Useful for bouncing between two folders.
Type cd /Users/druemclean/proj then hit Tab —
it autocompletes to projects/. Hit Tab twice when ambiguous to see all matches.
This eliminates 90% of typing.
When you run a command, it takes over your terminal until it finishes. That's "foreground." If you need
to stop it, you have a few options.
$ python long_running_script.py
{output.map((line, i) => (
{line}
))}
{running && !interrupted && (
▊ running...
)}
{!running && output.length > 0 && (
$ ▊
)}
⌃ C
Interrupt — politely asks the program to stop. Works 95% of the time. This is the one you already know.
⌃ Z
Suspend — pauses the program and gives you back the prompt. Resume with fg or kill with kill %1.
⌃ D
End-of-input. Closes interactive sessions like Python REPL or SSH. Different from interrupting.
command &
Run in background from the start. The & at the end means "don't block my terminal."
jobs
Lists what's running in the background of this terminal.
Some programs trap ⌃ C and ignore it. Try it twice. If it still won't die,
suspend with ⌃ Z and run kill %1. Last resort: close the terminal
window — but if it's a server or a long task, you'll lose work.
tmux is a "terminal multiplexer." It lets a terminal session keep running even after you close the window
or your laptop disconnects. You detach from a session (walk away)
and attach to it later (pick up where you left off).
The session itself never stopped.
You probably don't need tmux yet. It becomes useful when you run long Claude Code sessions
and don't want to lose them if the terminal closes, or when you start working on a remote server over SSH.
For local React/FastAPI dev where you can just relaunch, it's overkill.
{/* Visual hierarchy */}
{attached
? "Currently attached. Your terminal window is showing the session live."
: "Detached. The session is still running on your Mac (notice the timer kept going). Reattach any time, even after closing the terminal window."}
tmux
Start a new tmux session.
tmux new -s name
Start a session with a memorable name.
⌃B then D
Detach. Your stuff keeps running.
tmux ls
List running sessions.
tmux attach -t name
Reattach to a specific session.
⌃B then C
Create a new window inside the current session.
⌃B then %
Split the window into two side-by-side panes.
);
};
// ============================================================
// GIT SECTION — animated pipeline
// ============================================================
const GitSection = () => {
const accent = ACCENTS.git;
const [stage, setStage] = useState(0);
const stages = [
{ label: "Working Directory", desc: "Files you've edited but git hasn't been told about yet.", cmd: null },
{ label: "Staging Area", desc: "Files you've marked as ready to be saved together.", cmd: "git add ." },
{ label: "Local Commits", desc: "A permanent snapshot saved in your local git history.", cmd: "git commit -m 'message'" },
{ label: "Remote (GitHub)", desc: "Pushed to GitHub. Now Railway can deploy it. Now Tony can see it.", cmd: "git push" },
];
return (
Code goes through four stages. Each git command moves files from one stage to the next.
Click through the stages to see your changes travel.
{/* Pipeline visualization */}
{stages.map((s, i) => (
setStage(i)}
style={{
padding: "14px 12px",
background: stage >= i ? `${accent}20` : "rgba(255,255,255,0.02)",
border: `1px solid ${stage === i ? accent : `${accent}30`}`,
borderRadius: "6px",
cursor: "pointer",
transition: "all 0.3s ease",
opacity: stage >= i ? 1 : 0.5,
}}>
"What's changed?" Shows what's in working dir, staging, and what's been committed but not pushed.
git add .
Stage everything you've edited. The dot means "all of it."
git commit -m "..."
Save a snapshot with a message describing what changed.
git push
Send your local commits up to GitHub. Triggers Railway redeploy on OptionsEdge.
git pull
Pull down whatever's on GitHub. You don't need this often as a solo dev. Matters more when Tony pushes.
git log
See past commits. Press q to exit.
When Claude Code says "I committed and pushed," it ran git add, git commit,
git push. When something goes wrong (merge conflict, "rejected" errors, missing pushes),
knowing which stage broke is how you debug it. The pipeline is the diagnostic.
A server is just a program that waits for incoming requests
and sends back responses. Your React app asks "give me the options data" — a server answers. That's it.
Nothing magical about the word.
The confusing part is where servers run. There are two flavors and they live in completely different places.
Local server
Runs on your laptop. Started when you run npm run dev or uvicorn main:app.
Stops the moment you close the terminal. Only you can see it.{" "}
URL: localhost:5173 or 127.0.0.1:8000.
Remote server
Runs on a computer somewhere else (Railway, AWS, a VPS) 24/7. Has a public URL.
Anyone with the URL can reach it.{" "}
Your OptionsEdge on Railway is this.
{/* WiFi toggle demo */}
The WiFi test
Toggle the WiFi to see what survives. The answer reveals the whole mental model.
{/* Your laptop — always works */}
Your laptop
✓ localhost:5173
✓ localhost:8000
Always works. localhost = "this machine."
{/* WiFi connection */}
{wifi ? "WiFi" : "✗ OFF"}
{/* Railway */}
Railway (cloud)
{wifi ? "✓" : "✗"} optionsedge.app
{wifi ? "Reachable through internet." : "Need internet to reach it."}
{/* Connection 2 */}
{/* Tony */}
Tony's laptop
{wifi ? "✓ Sees Railway" : "✗ Can't reach"}
✗ Never sees localhost
Even on the same WiFi.
{wifi
? "Everything reachable. Tony can hit Railway, you can hit Railway, localhost works."
: "Internet gone. localhost still works (it's just your laptop). Railway unreachable for everyone."}
Tony has never been able to reach your localhost. Not on the same WiFi, not as a special favor.
localhost literally means "this exact computer." When npm run dev said
"Local: http://localhost:5173" — that URL is meaningless to anyone but you. To share with Tony you
push to GitHub → Railway redeploys → Tony hits the Railway URL.
npm's two jobs
npm install
Reads package.json, downloads every listed dependency into a local node_modules/ folder.
That folder gets huge (gitignored, never pushed). Run once after cloning a repo.
npm install X
Adds package X to your project. Updates package.json so the next person who clones gets it too.
npm run dev
Runs the "dev" script in package.json. For your projects this starts Vite (or Express) on localhost.
Hot-reloads as you save files.
npm run build
Compiles React into optimized static files for production. Railway runs this automatically when deploying.
Dev server (npm run dev): friendly, hot-reloads,
shows full error stacktraces, slow but easy to debug. Lives on your laptop only.
Production server (what Railway runs): optimized, minified,
hides errors from users, fast. Lives in the cloud, runs 24/7.
Same code, different mode. npm run build is what transforms dev → production.
);
};
// ============================================================
// PORTS SECTION — IPs, ports, URL anatomy, port collisions
// ============================================================
const PortsSection = () => {
const accent = ACCENTS.ports;
const [activePart, setActivePart] = useState("port");
const [bindings, setBindings] = useState({
3000: null,
5173: { name: "Vite (React dev)", color: "#10b981" },
8000: { name: "FastAPI backend", color: "#3b82f6" },
5432: { name: "PostgreSQL", color: "#06b6d4" },
});
const [bindResult, setBindResult] = useState(null);
const tryBind = (port, name, color) => {
if (bindings[port]) {
setBindResult({
success: false,
msg: `Error: listen EADDRINUSE: address already in use :::${port}`,
detail: `${bindings[port].name} is already there.`,
});
} else {
setBindings({ ...bindings, [port]: { name, color } });
setBindResult({ success: true, msg: `${name} bound to port ${port}`, detail: null });
}
};
const free = (port) => {
if (!bindings[port]) return;
const wasName = bindings[port].name;
setBindings({ ...bindings, [port]: null });
setBindResult({ success: true, msg: `Killed ${wasName} — port ${port} is now free`, detail: null });
};
const urlParts = [
{ id: "protocol", text: "https", desc: "Protocol — the 'language' the two computers will speak. http is plain, https adds encryption. Browsers show a padlock for https." },
{ id: "sep1", text: "://", desc: null },
{ id: "host", text: "options-edge.up.railway.app", desc: "Host — which computer to talk to. Either an IP address (like 127.0.0.1) or a name that DNS translates into an IP. Railway gave you this name." },
{ id: "sep2", text: ":", desc: null },
{ id: "port", text: "443", desc: "Port — which program ON that computer to talk to. 443 is the standard HTTPS port and is hidden by default. localhost:5173 means port 5173, where Vite is listening." },
{ id: "sep3", text: "", desc: null },
{ id: "path", text: "/api/options-chain", desc: "Path — which specific resource you want. The host:port gets you to a program; the path tells the program which feature to invoke." },
];
return (
Every computer has an IP address — its phone number on the
network. 127.0.0.1 is a special IP that always means "this exact computer" — that's localhost.
But one computer can run dozens of programs at once. So each program claims a{" "}
port — a numbered slot at that IP. The IP is the building, the
port is the suite number. Two programs cannot share a port, ever.
Each port can hold one program. Try starting another Vite while the first one is still running.
127.0.0.1 (your laptop)
{Object.entries(bindings).map(([port, prog]) => (
PORT
:{port}
{prog ? (
<>
● {prog.name}
) : (
(free)
)}
))}
{bindResult && (
{bindResult.msg}
{bindResult.detail && (
{bindResult.detail}
)}
)}
Common ports you'll see
3000
Express, old Create React App default
5173
Vite default — your gallery + financial-literacy-playground
8000 / 8080
FastAPI / Django / common alt-HTTP
5432
PostgreSQL default (your OptionsEdge database talks on this)
80
HTTP — hidden in URLs by default
443
HTTPS — hidden in URLs by default
Ports below 1024 (like 80 and 443) are "privileged" — they need root permission to bind to.
That's why dev servers all use ports above 1024 — no sudo required.
Means another process is already on that port. Either:
• You started a dev server in another terminal and forgot, or
• A previous run crashed without cleaning up.
Find it: lsof -i :5173 shows the PID using port 5173.
Kill it: kill -9 PID (replace PID with the number from lsof).
Then re-run your dev server.