DEV Community: Nadav Avisrur

I gave Claude Code a brain. here's what happened.

Nadav Avisrur — Mon, 16 Mar 2026 10:09:19 +0000

ok so I built something last week. not the point of this post though.

the point is HOW i built it. because I think I accidentally stumbled into a workflow that's kind of broken.

I built and shipped a full open source tool, solo, over a weekend. a monorepo with backend, frontend, CLI, landing page, demo videos, marketing content for 6 platforms, SEO, Discord server, security audit, npm packages published. 34 working sessions. one person.

the tool is clsh. I needed real terminal access on my phone so I built it for myself and open sourced it. but honestly thats not what I want to talk about. I want to talk about the system.

the problem with Claude Code sessions

if you've used Claude Code for anything serious, you know the pain. context resets. every new session starts from zero. you explain the same architecture, the same decisions, the same file structure, again and again. you lose momentum. you lose context. and the agent makes dumb mistakes because it doesnt remember what you decided 3 sessions ago.

I got frustrated enough to try something stupid: what if I gave Claude a brain?

obsidian as a context manager

so before I wrote a single line of code, I spent maybe a full day doing deep research. chatgpt, claude, reading docs, looking at how other people structure projects. and then I created an Obsidian vault that mirrors an actual company.

clsh.dev/
  00_Company/         ← identity, vision, mission
  01_RnD/             ← architecture, frontend, backend, infra, devops
  02_Product/          ← MVP definition, features, roadmap, vision
  03_Marketing/        ← social media, content, GTM, branding, SEO
  04_Community/        ← discord, github, contributors, growth
  05_Business/         ← competitors, market intel
  06_Legal/            ← licensing, security, privacy
  Docs/                ← source technical plan
  Handoffs/            ← session handoff notes (43 of them now)
  Templates/           ← reusable note templates
  Execution-Plan.md    ← THE source of truth
  VAULT-INDEX.md       ← navigation hub
  CLAUDE.md            ← agent instructions
  .claude/commands/    ← custom slash commands
  .claude/agents/      ← agent personas (7 of them)

every folder has an index file. every decision gets logged. every session ends with a handoff. the vault IS the project brain, and Claude Code reads it at the start of every session.

the init command

this was the most important part. I built a single command that scaffolds this entire vault structure. it creates every folder, every index file, every template, the execution plan skeleton, agent personas, custom commands, everything. one command and you go from empty folder to a fully structured project brain.

but the real work was before that. I spent hours with ChatGPT and Claude doing deep research on:

what departments does a solo dev actually need to think about?
whats the minimum viable structure for each?
how should files reference each other (wikilinks)?
what does a good execution plan look like for a 2-week project?

that research became the init command. and the init command became the foundation for everything.

the workflow commands

here's where it gets interesting. I wrote 8 custom Claude Code commands that basically turn Obsidian into an operating system for development:

/resume-clsh — reads the execution plan, finds the latest handoff, identifies which steps are unblocked, shows you exactly where you left off and what to do next. every session starts with this.

/wrap-up-clsh — updates the execution plan, updates all department files, creates a handoff note with what was done, what's next, what's blocked. every session ends with this. this is what gives the next session its memory.

/status — full dashboard. progress per phase, department health, social channels, blockers, next milestones.

/bug-fix — reads the vault docs, finds relevant code, fixes the bug, updates vault if there's a documentation gap.

/new-feature — checks the execution plan, creates a feature spec from template, plans the implementation, updates the features list.

/sprint — plans the week's work based on whats unblocked in the execution plan.

/vault-sync — syncs all changed files back to the vault after a batch of work.

the key insight is that every command reads from AND writes to the vault. so the knowledge compounds. session 34 has the full context of sessions 1-33, not because of some magic memory system, but because every session updated the same files.

parallel execution (this is where it gets wild)

my execution plan has "parallel groups" built in. steps that dont depend on each other can run simultaneously. so when I hit /resume-clsh, it doesn't just show me the next step. it shows me ALL unblocked steps and which agent personas should handle each one.

then I spawn a team. literally. Claude Code creates a team with multiple agents, each working in their own git worktree so they dont step on each other. one agent builds the backend. another builds the frontend. at the same time. then I merge the worktrees.

Team: "clsh-phase1b"
+---------------------------+  +---------------------------+
|  backend-engineer          |  |  frontend-engineer         |
|  Step 1.2 + 1.3            |  |  Step 1.4                  |
|  worktree: backend-core    |  |  worktree: frontend-core   |
+---------------------------+  +---------------------------+

this is not hypothetical. I have 7 agent personas defined: rnd-lead, frontend-engineer, backend-engineer, devops-engineer, product-manager, marketing-lead, community-lead. each one has a persona file that tells it what it owns, what tools it has, how to coordinate.

not just code

and this is the part I think most people miss. this system isn't just for writing code. the vault has marketing, SEO, community, legal, business intel. so when I ran /new-feature for "create demo video", Claude:

created a Remotion project (React-based video rendering)
built 5 animated scenes with iPhone frames
rendered the video to MP4
compressed it with ffmpeg
embedded it in the landing page
created Instagram composites (1080x1350) with brand colors
wrote captions for 6 different platforms
posted to Discord

when I ran the SEO workflow, it set up Google Search Console, submitted sitemaps, added meta tags, JSON-LD structured data, Open Graph tags. all tracked in 03_Marketing/SEO/SEO.md.

when I did the security audit, it found 4 critical and 9 high vulnerabilities, documented them all in 01_RnD/Security-Audit.md, and then I ran fix sessions that checked off each one. the vault tracked the entire thing.

43 handoff files. each one a snapshot of exactly where things stood at the end of that session.

the results

34 sessions over a weekend
88% complete (21/24 execution plan steps)
full monorepo: backend (node-pty + WebSocket + auth), frontend (React + xterm.js), CLI, landing page
npm published (3 packages), domain live, DNS configured, SSL
demo videos (Remotion), Instagram content (7 composites), marketing copy for 6 platforms
Discord server with bot, channels, roles
security audit + fixes
SEO infrastructure
all of this, solo

I'm not saying this is the only way to do it. but the idea of giving your AI coding agent a persistent, structured brain that it reads from and writes to every session... that changed everything for me.

want the setup?

I can share the exact Obsidian vault template + all 8 custom commands + the agent personas + the init command. everything you need to replicate this workflow for your own project.

just drop a comment asking for it and I'll DM you the zip.

or check out clsh if you're curious what I built with it. just a tool I needed for myself and decided to open source.

built with an unhealthy amount of coffee and an Obsidian vault that knows more about my project than I do

How I Built clsh: Phone-First Terminal Access to Your Mac

Nadav Avisrur — Sat, 14 Mar 2026 17:21:06 +0000

I use Claude Code a lot. Not "a few commands a day," full refactoring sessions that run for minutes at a time. And I kept running into the same problem: I'd walk away from my desk, grab my phone, and have zero visibility into what was happening.

Is it still running? Did it error out? Is it about to overwrite something it shouldn't?

I tried SSH clients. I tried web-based terminals. Every option had the same flaw: the iOS keyboard. Try typing kubectl get pods -n production --sort-by=.metadata.creationTimestamp on a touchscreen. It's miserable.

So I built clsh, an open-source tool that gives you real terminal access to your Mac from your phone, with a keyboard that actually works.

Since it's real PTY sessions, everything that runs in a terminal just works. Claude Code's TUI, Aider's diff view, tmux, vim, git, whatever. This turned out to be one of the most important use cases: with AI coding agents running long sessions, you need a way to monitor and control them from anywhere.

This is the story of how I built it, the technical decisions I made, and what I learned along the way.

The Core Architecture

clsh has three pieces: an agent that runs on your Mac, a web frontend you open on your phone, and a tunnel connecting them.

The Agent

The agent is a Node.js process running Express, WebSocket, and node-pty. When you start it, it spawns real PTY sessions. Not child_process.exec, not Docker containers, actual pseudoterminal sessions attached to your shell.

I chose node-pty over alternatives because it gives you true PTY semantics: SIGWINCH for resize, proper signal forwarding, and full ANSI escape sequence passthrough. If your terminal can do it locally, clsh can do it remotely.

Each session gets its own PTY and its own WebSocket connection. The agent tracks sessions in SQLite (WAL mode for concurrent reads) and authenticates requests with JWTs. When tmux is installed, sessions are wrapped in tmux, so they survive server restarts. Close your laptop, reopen, and your sessions are still there.

Phone Browser  <-->  WebSocket  <-->  node-pty (zsh)
Phone Browser  <-->  WebSocket  <-->  node-pty (tmux)
Phone Browser  <-->  WebSocket  <-->  node-pty (claude)

The Tunnel

clsh has a 3-tier tunnel system. It tries ngrok first (via the Node SDK, not the CLI), falls back to SSH tunneling via localhost.run (no account needed), and finally local WiFi if you're on the same network. When the agent starts, it opens a tunnel and gives you the URL + a QR code. Scan the QR code on your phone and you're connected.

The nice thing about the SDK approach is that the tunnel lifecycle is managed by the process. Agent starts, tunnel opens. Agent stops, tunnel closes. No dangling processes. The SSH fallback means you can use clsh without any third-party account at all.

Authentication works via one-time bootstrap tokens. The first time you connect, the agent generates a JWT signed with a secret stored in ~/.clsh/jwt_secret. The token is embedded in the URL. Subsequent connections use the JWT directly (stored in localStorage on the phone).

The Frontend

React 18 + Vite 6 + xterm.js 5.5 with the WebGL renderer. The frontend is designed phone-first: everything from the layout to the touch handling assumes a phone screen.

The Keyboard Problem (and Solution)

This was the hardest part of the entire project.

The iOS keyboard is designed for text, not terminals. You don't have Ctrl. You don't have fn. Arrow keys are there but buried. Tab requires switching layouts. Option and Command don't exist. Every terminal session becomes a fight with autocorrect and key prediction.

My solution was kind of radical: suppress the iOS keyboard entirely and build custom keyboard components for the phone.

clsh ships with two keyboard layouts. The default is IOSKeyboard, a 6-row iOS-style layout with oversized letter keys optimized for touch typing. The alternative is MacBookKeyboard, a pixel-perfect 5-row MacBook layout with the function row, modifier keys, and arrow cluster. Both render every key and map each press to the correct terminal escape sequence. Ctrl+C sends \x03. Arrow up sends \x1b[A. The key sizing follows Apple's proportions, scaled to fit a phone width.

The tricky part was modifier keys. On a physical keyboard, you hold Ctrl while pressing C. On a touchscreen, you can't hold two keys simultaneously. The solution: sticky modifiers. Tap Ctrl once to activate it (it highlights), tap your target key, and Ctrl automatically deactivates. Tap it twice to lock it on.

This small UX decision, making modifiers toggle instead of hold, transformed the phone terminal experience from "barely usable" to "surprisingly productive."

The Session Grid

When you're running multiple terminal sessions, you need to see them all. clsh shows a tmux-style 2x2 grid where each card displays a miniaturized live preview of the session.

The previews aren't screenshots. They're generated by reading the xterm.js buffer cell-by-cell (each cell's character, foreground color, and background color) and converting it to colored HTML spans. The result is a tiny, accurate, colorful representation of what each session is doing.

Tap any card to zoom into full-screen terminal mode. The grid feels like looking at your open MacBook from across the room, and tapping feels like sitting down at it.

Keyboard Skins (The Fun Part)

I didn't plan to build keyboard skins. It happened because I was staring at the default keyboard and thought "what if it was RGB like a gaming keyboard?"

clsh ships with six themes:

iOS Terminal: The default. 6-row layout with oversized letter keys, optimized for touch.
MacBook Silver: Clean, minimal, looks like an actual MacBook keyboard.
Gamer RGB: Animated rainbow gradient across the keys. Because why not.
Custom Painted: Each key a different color, like a paint palette exploded on your keyboard.
Amber Retro: Phosphor terminal aesthetic. Orange keys, dark background.
Ice White: Minimal, high-contrast, all white.

You can customize per-key colors and export skins as .kbd files. The entire skin system uses CSS custom properties, so themes are just variable swaps. Keyboard skins are the mechanical keyboard culture of phone terminals. I didn't expect it to be one of the most satisfying features to use.

Demo Mode

The landing page at clsh.dev works without any backend. It runs a demo mode that simulates terminal sessions with realistic typing, ANSI output, and interactive keyboard response.

Building a convincing demo was important because the entire product is about a feeling, the feeling of having your MacBook in your pocket. If someone visits the landing page on their phone and the demo makes them go "wait, this is actually usable," the product sells itself.

The demo auto-types commands at human-like speeds (80-140ms per character for Claude responses, faster for regular shell commands), renders real ANSI color output, and lets you tap the keyboard to see it respond. It runs on a 2-second backend connection timeout. If no backend is reachable, demo mode activates automatically.

The Tech Stack

Layer	Choice	Why
Frontend	React 18, Vite 6, Tailwind CSS v4	Fast dev, hot reload, CSS-first config
Terminal	xterm.js 5.5, WebGL renderer	Industry standard, GPU-accelerated
Backend	Node.js 20+, Express, ws	Lightweight, WebSocket-native
PTY	node-pty	Real terminal sessions, signal forwarding
Tunnel	ngrok / SSH / WiFi	3-tier fallback, no account required
Auth	jose (JWT)	No external dependencies
Database	better-sqlite3, WAL mode	Zero config, fast reads
Monorepo	Turborepo, npm workspaces	Parallel builds, shared types

The whole thing is about 55 source files. The agent is 11 files. The frontend is 44 (components, hooks, lib, demo engine). There's no build step for the landing page, it's static HTML deployed to Cloudflare Pages.

What I Learned

Phone-first is a different design language. Everything I know about web development assumes a cursor, a keyboard, and hover states. Designing for touch-only required rethinking every interaction. Buttons need to be bigger. Feedback needs to be immediate and visual (not just hover states). Tap targets need spacing.

xterm.js is incredibly capable. The WebGL renderer handles ANSI sequences, 256 colors, mouse events, and cursor positioning flawlessly. The addon ecosystem (fit, web-links, search) covers most needs. The buffer API made the colored preview feature possible.

Sticky modifiers change everything. This one UX pattern, making modifier keys toggle instead of hold, is the difference between "this is a toy" and "I can actually work from my phone."

Demo mode is marketing. The best way to sell a developer tool is to let developers use it immediately, for free, with no signup. Demo mode on the landing page does more for conversion than any amount of copy.

tmux integration is the secret weapon. Wrapping PTY sessions in tmux means they survive server restarts. Close your laptop, reopen it, and your sessions are still running. Combined with a static ngrok URL, this means your phone always connects to the same URL and finds its sessions waiting. It feels like a native app.

What's Next

clsh MVP is local-first: your Mac is the server, ngrok is the tunnel, your phone is the client. That's intentional. Zero cloud dependency, total control.

The roadmap:

Remote machines: Cloud VMs that are always on, accessible from anywhere
Claude bootstrap: A script that automatically duplicates your local dev environment (dotfiles, repos, configs) to a remote machine
Teams: Shared terminal sessions, presence indicators, multiple Claude Code instances working in parallel

The vision is your development environment as a service. Start solo with your Mac, scale to remote machines, graduate to team workspaces. All from your phone.

Try It

clsh is MIT licensed and open source. Under a minute to set up, zero config, zero signup:

git clone https://github.com/my-claude-utils/clsh && cd clsh
npm install
npm run dev

Or try the demo on your phone: clsh.dev

GitHub: github.com/my-claude-utils/clsh

If you have feedback, ideas, or want to contribute, issues and PRs are open. I'd especially love input on the keyboard UX and what features would make this useful for your workflow.