# repl_socket.py
from __future__ import annotations

import code
import io
import os
import socketserver
import threading
from contextlib import redirect_stderr, redirect_stdout, suppress
from typing import Any


def start_repl_socket(
    app: Any,
    *,
    namespace: dict[str, Any],
) -> str | None:
    class Handler(socketserver.StreamRequestHandler):
        def handle(self) -> None:
            locals_ = {**namespace, "app": app}

            text_rfile = io.TextIOWrapper(
                self.rfile,
                encoding="utf-8",
                errors="replace",
                newline=None,
            )
            text_wfile = io.TextIOWrapper(
                self.wfile,
                encoding="utf-8",
                line_buffering=True,
                write_through=True,
            )

            with suppress(Exception):
                with (
                    app.app_context(),
                    redirect_stdout(text_wfile),
                    redirect_stderr(text_wfile),
                ):
                    console = code.InteractiveConsole(locals=locals_)

                    print(f"{app.name} REPL (pid={os.getpid()})\n")

                    more = False
                    while True:
                        text_wfile.write("... " if more else ">>> ")
                        text_wfile.flush()

                        if not (line := text_rfile.readline()):
                            break

                        more = console.push(line.rstrip("\r\n"))

    socket_path = f"/tmp/api-repl.{os.getpid()}.sock"
    server = socketserver.ThreadingUnixStreamServer(socket_path, Handler)
    os.chmod(socket_path, 0o600)

    threading.Thread(target=server.serve_forever, daemon=True).start()
    return socket_path

The nice thing about console.push(...) is that it behaves like a real Python REPL:

• multi-line blocks work
• bare expressions print their values
• tracebacks show up correctly

The rest is just plumbing:

• TextIOWrapper turns the socket into normal text streams
• redirect_stdout(...) and redirect_stderr(...) make print() and errors show up in the client
• app.app_context() makes Flask globals such as current_app work immediately

Then wire it into your app and expose whatever objects you want in the session:

# main.py
from flask import Flask

from repl_socket import start_repl_socket


app = Flask(__name__)


@app.get("/")
def healthcheck():
    return {"status": "ok"}


if __name__ == "__main__":
    socket_path = start_repl_socket(
        app,
        namespace={"config": app.config, "db": None},
    )
    if socket_path:
        print(f"production REPL listening on {socket_path}")
    app.run()

Start the app, then attach with nc:

uv run python main.py
nc -U /tmp/api-repl.<pid>.sock

An example session looks like this:

main REPL (pid=63503)

>>> 1 + 1
2
>>> from flask import current_app
>>> current_app.name
'main'
>>> with app.test_request_context("/"):
...     from flask import request
...     print(request.path)
...
/

A few nice details:

• the transport is local-only; no TCP debug port needed
• chmod 600 keeps the socket owner-only
• each worker process gets its own /tmp/api-repl.<pid>.sock

For request-bound objects such as request or session, create a request context manually:

with app.test_request_context("/"):
    ...

That is it. No extra dependency, and no need to build your own eval() loop.

Repo (the exact files I use): github.com/aminroosta/opencode-sandbox

• deny home directory reads/writes by default.
• deny process-exec by default.
• start with an empty environment (env -i).

There are three layers:

1. opencode-sandbox (a tiny wrapper script)
2. opencode-dev-only.sb (a sandbox profile)
3. ~/.config/opencode/opencode.json (OpenCode config defaults)

The Wrapper Script

The wrapper does two important things:

• runs OpenCode under sandbox-exec -f opencode-dev-only.sb
• clears the environment with /usr/bin/env -i and opts out of some features via OPENCODE_DISABLE_*

#!/usr/bin/env bash
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname $(realpath "$0"))" && pwd)"
PROFILE="$SCRIPT_DIR/opencode-dev-only.sb"

OPENCODE_BIN="$(command -v opencode || true)"

exec /usr/bin/env -i \
  HOME="${HOME:-}" \
  PATH="${PATH:-}" \
  EDITOR="${EDITOR:-}" \
  VISUAL="${VISUAL:-}" \
  TERM="${TERM:-}" \
  TMPDIR="${TMPDIR:-}" \
  COLORTERM="${COLORTERM:-}" \
  OPENCODE_DISABLE_AUTOCOMPACT=true \
  OPENCODE_DISABLE_PRUNE=true \
  OPENCODE_DISABLE_LSP_DOWNLOAD=true \
  OPENCODE_DISABLE_DEFAULT_PLUGINS=true \
  OPENCODE_DISABLE_MODELS_FETCH=true \
  OPENCODE_DISABLE_SHARE=true \
  OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=true \
  OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=true \
  OPENCODE_DISABLE_EXTERNAL_SKILLS=true \
  OPENCODE_EXPERIMENTAL_DISABLE_FILEWATCHER=true \
  OPENCODE_DISABLE_TERMINAL_TITLE=true \
  OPENCODE_DISABLE_FILETIME_CHECK=true \
  /usr/bin/sandbox-exec -f "$PROFILE" "$OPENCODE_BIN" "$@"

  # If your OpenCode auth relies on environment variables (for example `OPENAI_API_KEY`), you need to explicitly forward them too.

That OPENCODE_DISABLE_* list is intentional: fewer downloads and fewer background features means fewer sandbox allowances (and fewer surprises).

The Sandbox Profile

Two important rules:

1. Deny writes globally (then allow writes only where needed)
2. Deny reads of your home directory (then allow reads only where needed)

Key lines (trimmed):

(allow default)

; Put broad denies first, then carve out explicit allows.
(deny file-write*)
(deny file-read* (subpath "/Users/<you>"))

; Default-deny subprocess execution.
(deny process-exec)

; Allow system binaries + your toolchain.
(allow process-exec (subpath "/bin"))
(allow process-exec (subpath "/usr/bin"))
(allow process-exec (subpath "/opt/homebrew"))

; Re-block high-risk launcher helpers.
(deny process-exec (literal "/bin/launchctl"))
(deny process-exec (literal "/usr/bin/open"))
(deny process-exec (literal "/usr/bin/osascript"))

; Workspace: allow read/write only here.
(allow file-read* (subpath "/Users/<you>/dev"))
(allow file-write* (subpath "/Users/<you>/dev"))

The full profile in the repo includes the practical stuff you tend to need in a real dev session:

• temp dirs: /private/tmp, /private/var/folders
• OpenCode state: ~/.config/opencode, ~/.local/share/opencode, ~/.cache/opencode, etc.
• tool managers: mise, uv, language runtimes, homebrew
• minimal metadata reads (file-read-metadata) so path traversal works

Recommended OpenCode Settings

The OS sandbox is the hard boundary.
OpenCode config is the “seatbelt” that still helps even when you forget to use the wrapper.

From ~/.config/opencode/opencode.json, the settings I recommend for a sandboxed setup:

{
  "$schema": "https://opencode.ai/config.json",
  "share": "disabled",
  "autoupdate": false,
  "server": { "mdns": false },

  "lsp": false,
  "formatter": false,
  "snapshot": false,
  "disabled_providers": ["opencode"],

  "permission": {
    "*": "ask",
    "external_directory": {
      "*": "ask",
      "$HOME/dev/*": "allow",
      "/tmp/*": "allow"
    }
  },

  "agent": {
     "build": {
       "mode": "primary",
       "tools": {
         "*": false,
         "apply_patch": true,
         "batch": true,
         "glob": true,
         "grep": true,
         "invalid": true,
         "ls": true,
         "read": true,
         "task": true,
         "webfetch": true,
         "external_directory": true,
         "bash": true
       }
     },
   }
}

• share: disabled: reduces accidental data leak.
• autoupdate: false: avoids auto-downloading and executing new binaries.
• server.mdns: false: avoids broadcasting a local service via mDNS.
• permission: prompts before doing anything that touches the filesystem / shell / external dirs.
• tools: enable only what you need.

Limitations

• This setup does not restrict outbound network by default.
• Sandboxing reduces blast radius; it does not make prompt injection “go away”.

I wanted something for small, repetitive chores: rename layers, nudge spacing normalize corner radius, etc. So I built figma-chatbot: a local bridge that lets Claude execute JavaScript inside a running Figma Desktop document, using the Figma plugin API. That makes prompts like “change the button color to red” possible.

How It Works

There are two parts, both running locally:

• a tiny Figma plugin window that stays open in Figma
• a localhost bridge that forwards requests from Claude to that plugin

The bridge is only there to connect Claude to the Figma plugin runtime.

Edits happen inside the Figma plugin, where the document is writable.

Setup

figma-chatbot is local-first by design: it runs on your machine and talks to your Figma Desktop app over localhost.

It uses Bun as the runtime for the local bridge.

What the setup looks like:

1) Claude Code side (install + sanity check)

/plugin marketplace add aminroosta/figma-chatbot
/plugin install fig@fig

/fig:setup

2) Figma Desktop side (import the dev plugin)

• Plugins -> Development -> Import plugin from manifest
• select ~/.claude/plugins/marketplaces/fig/chatbot/ (it contains manifest.json)
• run the plugin (Figma command palette: Cmd+/, search “chatbot”) and keep its window open

3) Back in Claude Code (start the bridge)

/fig:go
# This uses the bridge under the hood to evaluate JS snippets.

The plugin window shows connection state. When it says “Connected”, Claude can send edits.

Using It

Once the bridge is running, prompts like this become possible:

• “Find every instance of Button, make the fill red, and align the padding across variants.”
• “Prefix everything on this page with Marketing/, except frames that already have a prefix.”
• “Rename these layers with a clean scheme, then center the viewport on them.”

If you want to try it, the repo is here: https://github.com/aminroosta/figma-chatbot

• Step 1: write a tech spec (maybe informal; maybe just a Markdown file in Vimwiki).
• Step 2: add a few TODO tasks (obvious, low-hanging fruit that I should pick up next).

# Implement 2FA with SMS

- links to third-party SMS provider |
- links to Figma designs            |<- my understanding on day 1
- functional requirement 1          |
- functional requirement 2          |


# TODO
- [ ] Add a `user_sms` table + migration |
- [ ] Add a `POST /v1/sms/pin` API       |<- low-hanging fruit

• Step 3: implement the TODO items.
• Step 4: think about what to do next.

Go back to step 3 and repeat until the project is complete.

The way I use the Ralph Loop now isn’t too different from that approach; the key difference is that the TODOs are done by LLMs (GPT-5.2 (xhigh) or Opus 4.5 (max)).

I use OpenCode with a script to automate most of step 3 (implementing the TODO items).

ralph.ts    # it's somewhere on my PATH
ralph.md    # the system prompt for the Ralph Loop

# <current project files>
.opencode/
├── opencode.json # OpenCode permission/settings
├── log-sms.md    # append-only log for the LLM
└── prd-sms.md    # the PRD file

The setup is dead simple. I run ralph.ts <iterations> .opencode/prd-<name>.md. The script takes the ralph.md system prompt, inlines the paths to .opencode/prd-<name>.md and .opencode/log-<name>.md, and runs a new OpenCode session. It’s basically a for loop. The system prompt (ralph.md) instructs the LLM to mark the TODO item as complete, append progress to .opencode/log-<name>.md, and commit the changes.

Here is the full prompt ralph.md:

# Ralph Agent Instructions

You are an autonomous coding agent responsible for executing tasks within a software project.

## Your Task Pipeline

1.  **Contextual Review:**
    * Read the PRD at `RALPH_PRD_PATH`.
    * Read the progress log at `RALPH_LOG_PATH`.
2.  **Incremental Planning:**
    * Decide on a single, granular step to move the project closer to the full PRD implementation.
    * Steps need not be sequential, pick the one that feels right as the next step.
3.  **Execution:**
    * Implement that single step -- this is where you will spend most of your time.
4.  **Validation:**
    * Do everything that is available to verify that the changes are correct.
5.  **Version Control:**
    * Commit code changes with the message: `feat: [Item Title]`.
    * *Note: Skip `.opencode/` folder changes and any existing untracked files.*

## Progress Log Format
*Append-only. Information density is key.*

\`\`\`md
[short commit hash]
- informative (not prescriptive) notes to future self;
  such as learnings, patterns, gotchas, and/or useful snippets.
\`\`\`

> **Note:** The "Learnings" section is vital for helping future iterations pick up the next steps effectively.

---

## After Completing the Step

* Mark the step as complete in the `# Suggested Next Steps` section of `RALPH_PRD_PATH`.
* If there aren't enough steps left, add a new step to find more steps.
    * The goal is to include a dedicated step where you act as a slow, deliberate, and analytical thinker: an experienced architect and a rigorous QA specialist, to identify future steps.
* Improve existing steps, remove those that no longer apply (if any), and sort them by readiness to be picked up.

## Core Principles

* **Atomic Progress:** Work on **ONE** step at a time and commit frequently.
* **Excellence:** Strive for high-quality implementation in every iteration.

The .opencode/prd-sms.md might look something like this:

We are building SMS authentication with provider XYZ.
You can read the docs at http://xyz.com/docs/sms/api

Use the Figma MCP to inspect these node IDs: 110-5501 110-5729 290-8616

# Suggested Next Steps

- [ ] Add a `user_sms` table + migration
- [ ] Add a `POST /v1/sms/pin` API
- [ ] Study what needs to be done next and add a few more suggested steps.

And the ralph.ts script is the glue that runs the loop, plus a few extra niceties like opening the OpenCode web UI so I can inspect progress more easily.

Here is the full ralph.ts click to download.

I hope you find this useful. This has significantly changed how I write code in 2026.
The PRD becomes of utmost importance: I spend a lot of time manually editing it to make sure it’s solid. I gave a short example above, but usually instead of instructions like “read this URL” or “use the Figma MCP”, I do those ahead of time and put the materials somewhere on the filesystem so they’re easily accessible to the LLM. We want to avoid extra cognitive overhead for the LLM (this is called context rot).

Of course, not everything is sunshine and rainbows after the loops are done. I find myself adding a few more TODO items just to clean the slop; or, at worst, manually editing the code. I’d say slop cleanup takes about 60% of my time, but it’s still worth it because I’m 2x to 3x faster and much less mentally exhausted at the end of the day.

Years ago I started as an embedded developer. Back then, the limited resources were RAM and CPU, so I wrote C and sometimes even assembly! Now, with LLM agents on the rise, the new limited resource is the context window and it’s a precious resource!

Do you remember prompt-engineering? The next evolution of that is called context engineering and skills are the latest approach to do that.

A skill is just a folder with a SKILL.md plus a few scripts:

<skill name>/
├── SKILL.md   # includes frontmatter with "name" & "description"
└── scripts/
    ├── <helper script>.sh
    └── <helper script 2>.py

Only the skill name and description are loaded into the context window. The LLM agent loads skills on demand.

Here’s what I have learned while writing skills:

• SKILL.md should be as informative as possible: information density is the key.
• Be descriptive and avoid being prescriptive: describe how things work. Avoid “do X then Y” at all costs!
• Draft → then rewrite-from-scratch: once you have a messy first pass of SKILL.md, ask the LLM to rewrite it from scratch, emphasizing: be informative, not prescriptive, information density is the key. The rewrite is usually much smaller and easier to edit.
• Scripts matter: the scripts/ directory lets the agent do complex, frequent tasks without polluting the context window.

Example skill: OpenSCAD + BOSL2

OpenSCAD is the go-to CAD tool for software devs: you write .scad code, and it renders 3D geometry. BOSL2 is a batteries-included OpenSCAD library.

My use-case is simple: design small 3D parts I can print.

openscad/SKILL.md: this is what I mean by “information dense”.

---
name: openscad
description: "Design 3D printable objects using OpenSCAD with the BOSL2 library. Use when the user wants to create, modify, or render 3D models (.scad files)."
---

# OpenSCAD BOSL2 Quick Reference

## 1. Transforms & Constants
### Translation & Scaling
- `move([x,y,z])`, `up(z)`, `down(z)`, `fwd(y)`, `back(y)`, `left(x)`, `right(x)`
- `scale([x,y,z])`, `scale(s)`, `xscale(s)`, `yscale(s)`, `zscale(s)`
### Rotation & Mirroring
- `rot([ax,ay,az])`, `rot(a, v=[x,y,z])`, `rot(from=V1, to=V2)`
- `xrot(a)`, `yrot(a)`, `zrot(a)`. All accept `cp=[x,y,z]` to rotate around a point.
- `mirror(v)`, `xflip()`, `yflip()`, `zflip()`. Accept `x|y|z=offset` for plane selection.
### Skewing
- `skew(sxy, sxz, syx, syz, szx, szy)`: `sAB` skews axis A as you move along axis B.
### Direction Constants
- `LEFT [-1,0,0]`, `RIGHT [1,0,0]`, `FWD [0,-1,0]`, `BACK [0,1,0]`, `DOWN [0,0,-1]`, `UP [0,0,1]`, `CENTER [0,0,0]`

## 2. Distributors
- `xcopies(spacing|l=, n=2, sp=)`, `ycopies(...)`, `zcopies(...)`
- `line_copies(spacing=V, n=, p1=, p2=)`
- `grid_copies(spacing=, n=, size=, stagger=true|alt, inside=polygon)`
- `xrot_copies(n=)`, `yrot_copies(n=)`, `zrot_copies(n=)`, `arc_copies(n, r, sa, ea)`
- `xflip_copy()`, `yflip_copy()`, `zflip_copy()`, `mirror_copy(v)`

## 3. 3D Shapes (Enhanced Primitives)
- **Common Args:** `anchor`, `spin` (Z-rot), `orient` (tilt Z-axis to vector).
- `cuboid(size, rounding=, chamfer=, edges=, except_edges=)`
- `cyl(l, r|d, rounding=, chamfer=, rounding1=, rounding2=)`
- `spheroid(r|d, circum=true, style="aligned"|"icosa"|"octa")`
- `tube(id=, od=, h=, wall=)`
- `cube()`, `cylinder()`, `sphere()` are overridden to support `anchor/spin/orient`.

## 4. Positioning & Attachments
### The Anchor System
- **Definition:** Anchors are vectors `[x,y,z]` (components `-1` to `1`) defining points on/in a shape.
- **Logic:** `anchor=A` translates geometry so point `A` sits at the local origin `[0,0,0]`.
- **Standard Anchors:** `CENTER [0,0,0]`, `UP [0,0,1]`, `DOWN [0,0,-1]`, `LEFT [-1,0,0]`, `RIGHT [1,0,0]`, `FWD [0,-1,0]`, `BACK [0,1,0]`.
- **Combinations:** Sum vectors for corners/edges (e.g., `UP+RIGHT` is `[1,0,1]`).

### Transform Order
1. **Anchor:** Translates selected point to origin.
2. **Spin:** Z-axis rotation (in degrees) applied after anchoring.
3. **Orient:** Tilts the Z-axis to align with a target vector.

### Attachment Modules (Parent-Child)
- `position(P_ANCHOR)`: Moves child's origin to parent's `P_ANCHOR`. No rotation.
- `align(P_ANCHOR, C_ANCHOR)`: Moves child so its `C_ANCHOR` is flush with parent's `P_ANCHOR`. No rotation.
- `attach(P_ANCHOR, C_ANCHOR)`: Joins `C_ANCHOR` to `P_ANCHOR` and **rotates** child so its local `UP` matches parent's `P_ANCHOR` normal.
- `attach(P_ANCHOR)`: Single-argument form. Child is attached to parent's face; child's own `anchor` and `orient` are respected.
- `attach_part(name)`: Selects sub-geometry (e.g., `"inside"` of a `tube()`).
- `show_anchors(s=)`: Visualizes anchors. Red flag = Y+ direction, Blue flag = Z+ direction.

### Relative Transforms
- `up()`, `down()`, `fwd()`, `back()`, `left()`, `right()`: Directional translations.
- `zrot()`, `xrot()`, `yrot()`: Axis-specific rotations.
- `recolor("color")`: Applies color to VNFs and complex geometries.

## 5. Tagged Operations & Boolean Logic
- **Tags:** `tag("name")` labels geometry for boolean operations. `tag("")` clears tags.
- **Diff:** `diff(remove, keep)` subtracts "remove" tagged children from the main geometry. "keep" objects are preserved but don't subtract.
- **Intersect:** `intersect(intersect, keep)` keeps only the overlap with "intersect" tagged objects.
- **Hull:** `conv_hull(keep)` computes the convex hull of children, excluding those tagged "keep".
- **Masking:** `edge_mask(edges)` and `corner_mask(corners)` align standard 3D masks (auto-tagged "remove") to parent edges/corners.
- **Profiling:** `edge_profile(edges)` extrudes 2D profiles along edges. `corner_profile(corners, r)` applies 3D profiles to corners.
- **Scope:** Tagged operations work across the entire child hierarchy, allowing "holes" to be defined deep within nested modules.

## 6. Making Custom Attachables
```openscad
module my_shape(..., anchor=CENTER, spin=0, orient=UP) {
    attachable(anchor, spin, orient, size=[x,y,z], r=, l=, vnf=, anchors=) {
        geometry();
        children();
    }
}
```
- **Named Anchors:** `anchors=[named_anchor(name, pos, orient, spin), ...]`
- **Overrides:** `override=[ [ANCHOR, [pos, dir, spin]], ... ]`

## 7. Common Functions
- **Utility:** `typeof(x)`, `is_def(x)`, `any(l)`, `all(l)`, `default(val, dflt)`, `first_defined(list)`.
- **Args:** `get_anchor(anchor, center)`, `get_radius(r1, d1, r, d)`, `scalar_vec3(v)`.
- **Math:** `lerp(a, b, u)`, `sum(v)`, `mean(v)`, `quant(x, y)`, `constrain(v, min, max)`, `posmod(x, m)`.
- **Lists:** `last(l)`, `idx(l)`, `reverse(l)`, `flatten(l)`, `select(l, start, end)`.
- **Vectors:** `unit(v)`, `v_mul(v1, v2)`, `vector_angle(v1, v2)`, `path3d(pts)`, `path2d(pts)`.
- **Matrices:** `move/rot/scale` as functions return 4x4 matrices. `apply(mat, pts)` applies them.

## 8. Tooling & Scripts
The following scripts are available at ./scripts/<script.sh> relative to this SKILL.md file.

```bash
# Installs the BOSL2 library in $HOME/Documents/OpenSCAD/libraries/BOSL2/
bash ./scripts/ensure_bosl2.sh

# Validate a SCAD file
./scripts/scad_tool.py validate --in path/to/file.scad

# Render an STL
./scripts/scad_tool.py stl --in path/to/file.scad --out output.stl

# Take Screenshots:
# Single isometric view
openscad/scripts/scad_tool.py screenshots --in path/to/file.scad --preset single

# Standard views (front, back, left, right, top, bottom, iso)
openscad/scripts/scad_tool.py screenshots --in path/to/file.scad --preset standard

# Custom angles (azimuth:elevation)
openscad/scripts/scad_tool.py screenshots --in path/to/file.scad --angles 45:30,90:45

# Turntable (360 rotation with 10 degree steps)
openscad/scripts/scad_tool.py screenshots --in path/to/file.scad --turntable 10
```

## 9. Resources & Documentation
- **Cheat Sheet:** [BOSL2 CheatSheet](https://github.com/BelfrySCAD/BOSL2/wiki/CheatSheet) - Quick syntax overview.
- **Tutorials:** [BOSL2 Tutorials](https://github.com/BelfrySCAD/BOSL2/wiki/Tutorials) - In-depth guides.
- **Alphabetical Index:** [AlphaIndex](https://github.com/BelfrySCAD/BOSL2/wiki/AlphaIndex) - Every function, module, and constant.

## 10. Visual Debugging & Inspection
- **Modifiers:** `#` (Debug: transparent red, shows `diff` removals), `%` (Background: transparent gray ghost), `!` (Root: isolate subtree), `*` (Disable: ignore subtree).
- **Coloring:** `color("name", alpha)` supports SVG color names (e.g., "Tomato", "DodgerBlue"). Alpha < 1.0 enables overlap inspection.
- **BOSL2 Tools:** `show_anchors(s=)` (Red=Y+, Blue=Z+), `recolor("color")` for VNFs, `half_of(DIR)` for cross-sections.

The scripts are the hammer!

They let the agent take screenshots, validate geometry, render STLs, and install BOSL2 without wasting the context window.

openscad/scripts/ensure_bosl2.sh:

#!/usr/bin/env bash
# Install or verify BOSL2 library for OpenSCAD
# ...

openscad/scripts/scad_tool.py:

#!/usr/bin/env -S uv run --script
"""OpenSCAD helper: validate, render STL, and take screenshots.

Mac-only version with preset screenshot modes and custom angle support.
"""

# ...

# screenshots subcommand
# - preset: single/iso/ortho/standard
# - views: iso/front/top/etc.
# - angles: custom az:el
# - turntable: 360 rotation

Using the skill: building a tray step-by-step

1. ask for a tiny change
2. render a screenshot
3. repeat

Here are my prompt to build a part.

Prompt 1 — “using openscad skill, add a tray.scad file having a cuboid of size 15 cm x 5 cm x 5mm”

Prompt 2 — “update tray.scad to have snap_pin_socket() holes on the 15 cm x 5mm side with 3 cm spacing between the holes”

Prompt 3 — “refactor that into a module called swall() (short for socketted wall) for re-use”

swall = socketed wall. This is where BOSL2’s attachable() starts paying off.

Prompt 4 — “add two perpendicular swalls to the floor part, color them differently”

Prompt 5 — “add a Silver cuboid to the back of the tray”

Prompt 6 — “move red walls up to sit flush with the blue floor”

Summary

• Information density wins
• Scripts are context-efficient
• Descriptive beats prescriptive

Here is my attempt at moving my entire development setup to a container. This works well if you use tmux and neovim. The goal: isolate untrusted code from the host while keeping a comfortable dev experience.

How It Works

The setup uses three files that work together:

dev.sh (orchestrator)
   │
   ├─► Builds image from Dockerfile (base OS + tools)
   │
   ├─► Runs setup.sh inside container (configures dotfiles, mise, nvim plugins etc.)
   │
   ├─► Commits the result (so setup only runs once)
   │
   └─► Launches tmux in a fresh container from the committed image

• Isolated: ~/.ssh, browser data, credentials, everything outside the project
• Shared: the ~/dev directory (mounted read-write)

1. Dockerfile: The Base Image

This builds a minimal Fedora image with core dev tools.

FROM fedora:latest

# Install core tools
RUN dnf install -y \
    neovim \
    tmux \
    git \
    curl \
    wget \
    gcc \
    gcc-c++ \
    make \
    ripgrep \
    fd-find \
    fzf \
    openssh-clients \
    ca-certificates \
    sudo \
    glibc-langpack-en \
    the_silver_searcher \
    ncdu \
    btop \
    && dnf clean all

ENV LANG=en_US.UTF-8
ENV LANGUAGE=en_US:en
ENV LC_ALL=en_US.UTF-8
ENV TERM=xterm-256color
ENV COLORTERM=truecolor

ARG USERNAME=amin
ARG USER_UID=1000
ARG USER_GID=1000

RUN groupadd --gid ${USER_GID} ${USERNAME} \
    && useradd --uid ${USER_UID} --gid ${USER_GID} -m ${USERNAME} \
    && echo "${USERNAME} ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/${USERNAME} \
    && chmod 0440 /etc/sudoers.d/${USERNAME}

COPY setup.sh /tmp/setup.sh

USER ${USERNAME}
WORKDIR /home/${USERNAME}

Notes:

• The user creation matches the host UID/GID so mounted files have correct permissions
• sudo is passwordless for convenience

2. setup.sh: Personal Environment Setup

This script runs once inside the container to set up the dotfiles and tools.

#!/bin/bash

readonly GITHUB_REPO="your-username/dot-files-repo"

# Clone dotfiles using SSH (agent forwarded from host)
git clone \
  -c core.sshCommand="ssh -o StrictHostKeyChecking=no" \
  git@github.com:${GITHUB_REPO}.git \
  && mv dot-files/.git . \
  && git checkout -- . \
  && rm -rf dot-files

# Install mise (manages node, python, etc.)
curl https://mise.run | sh

# Install uv (fast Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

source ~/.bashrc

# Install language runtimes via mise
mise use -g node@latest
mise use -g bun@latest

# Install direnv for per-project env vars
curl -sfL https://direnv.net/install.sh | bash

# Install neovim plugins
nvim --headless "+Lazy! sync" +qa

git config --global user.email "your-email@example.com"
git config --global user.name "your name"

3. dev.sh: The Orchestrator

It handles SSH agent forwarding (different on macOS vs Linux) and the build-setup-commit flow.

#!/usr/bin/env bash
set -euo pipefail

readonly IMAGE_NAME="dev"
readonly VM_SOCKET="/tmp/ssh-agent.sock"

ssh_tunnel_pid=""

cleanup() {
    if [[ -n "$ssh_tunnel_pid" ]]; then
        kill "$ssh_tunnel_pid" 2>/dev/null || true
    fi
}

### SSH Agent Forwarding

# SSH keys stay on the host, but the container can use them.
# macOS runs containers in a Linux VM, so we tunnel the socket through:
setup_macos() {
    # Forward host's SSH agent socket into the Podman VM
    podman machine ssh -- -R "${VM_SOCKET}:${SSH_AUTH_SOCK}" -N &
    ssh_tunnel_pid=$!
    sleep 1
    podman machine ssh -- chmod 777 "$VM_SOCKET"

    run_opts+=(
        -v "${VM_SOCKET}:${VM_SOCKET}"
        -e "SSH_AUTH_SOCK=${VM_SOCKET}"
    )
}

# Linux can mount the socket directly:
setup_linux() {
    local socket_dir="/run/user/$(id -u)"

    run_opts+=(
        -v "${socket_dir}:${socket_dir}"
        -e "SSH_AUTH_SOCK=${SSH_AUTH_SOCK}"
        --network=host
        --ulimit=host
    )
}

### Build, Setup, and Commit

main() {
    trap cleanup EXIT

    # Build the base image from Dockerfile
    podman build -t "${IMAGE_NAME}:latest" .

    declare -a run_opts=(
        --replace
        -it
        --detach-keys="ctrl-@"
        --name "${IMAGE_NAME}-temp"
        --userns=keep-id        # Maps container UID to your host UID
        --security-opt label=disable
    )

    case "$(uname)" in
        Darwin) setup_macos ;;
        *)      setup_linux ;;
    esac

    # Run setup.sh and commit the result
    podman run "${run_opts[@]}" "${IMAGE_NAME}:latest" /tmp/setup.sh
    podman commit "${IMAGE_NAME}-temp" "${IMAGE_NAME}:updated"

    ### Launch the Dev Environment

    # Fresh options for the final container
    run_opts=(
        --rm                    # Delete container on exit
        -it
        --detach-keys="ctrl-@"
        --userns=keep-id
        --security-opt label=disable
    )

    case "$(uname)" in
        Darwin) setup_macos ;;
        *)      setup_linux ;;
    esac

    # Mount ONLY the project(s) directory - nothing else
    run_opts+=(-v "${HOME}/dev:/home/amin/dev")

    podman run "${run_opts[@]}" "${IMAGE_NAME}:updated" tmux
}

main "$@"

• --userns=keep-id: The host UID maps to the container user, so file permissions work correctly on mounted volumes
• --security-opt label=disable: Disables SELinux labeling (avoids permission issues with mounts)
• --detach-keys="ctrl-@": Changes the detach sequence from ctrl-p ctrl-q (conflicts with tmux)

Why Podman?

I’m using podman instead of Docker because it runs rootless by default.

MacOS native workspaces include transition animations that create noticeable delays when switching between them. Adjusting system settings cannot fully remove this lag. However Aerospace, a macOS window manager inspired by i3, can be used to remove the animation delay.

Installing Aerospace and Setting Up the Config

Aerospace can be installed via Homebrew (brew install --cask nikitabobko/tap/aerospace) and is configured through ~/.config/aerospace/aerospace.toml.

# Default layout settings
default-root-container-layout = 'accordion'
default-root-container-orientation = 'auto'

# Zero out gaps for no wasted space
[gaps]
inner.horizontal = 0
inner.vertical = 0
outer.left = 0
outer.bottom = 0
outer.top = 0
outer.right = 0

# Keybindings for workspace switching (we'll enhance this with a script)
[mode.main.binding]
ctrl-h = 'exec-and-forget source ~/.config/aerospace/aerospace.sh && switch_workspace -1'
ctrl-l = 'exec-and-forget source ~/.config/aerospace/aerospace.sh && switch_workspace +1'
ctrl-shift-l = 'exec-and-forget source ~/.config/aerospace/aerospace.sh && move_to_workspace +1'
ctrl-shift-h = 'exec-and-forget source ~/.config/aerospace/aerospace.sh && move_to_workspace -1'

# Make all new windows floating by default
[[on-window-detected]]
run = ['layout floating']

Every app window floats freely now—no more tiling.

The Magic Trick: A Bash Script for Navigation

A bash script at ~/.config/aerospace/aerospace.sh calculates next/previous workspaces.

It uses two functions:

• switch_workspace for changing workspaces
• move_to_workspace for shifting the active window with the switch

These are bound to ctrl+h/l for navigation and ctrl+shift+h/l for moving windows.

switch_workspace() {
  offset=$1
  workspaces="1 2 3 4"
  current_workspace=$(aerospace list-workspaces --monitor focused --visible)
  workspaces_array=($workspaces)
  
  # Find current index
  for i in "${!workspaces_array[@]}"; do
    if [ "${workspaces_array[i]}" = "$current_workspace" ]; then
      current_index=$i
      break
    fi
  done
  
  # Calculate target without wrapping
  target_index=$((current_index + offset))
  if (( target_index < 0 )); then
    target_index=0
  elif (( target_index >= ${#workspaces_array[@]} )); then
    target_index=$(( ${#workspaces_array[@]} - 1 ))
  fi
  
  # Switch
  aerospace workspace "${workspaces_array[target_index]}"
}

move_to_workspace() {
  offset=$1
  workspaces="1 2 3 4"
  current_workspace=$(aerospace list-workspaces --monitor focused --visible)
  workspaces_array=($workspaces)
  
  # Find current index
  for i in "${!workspaces_array[@]}"; do
    if [ "${workspaces_array[i]}" = "$current_workspace" ]; then
      current_index=$i
      break
    fi
  done
  
  # Calculate target with wrapping for moving
  target_index=$(( (current_index + offset + ${#workspaces_array[@]}) % ${#workspaces_array[@]} ))
  target_workspace="${workspaces_array[target_index]}"
  
  # Move and switch
  aerospace move-node-to-workspace "$target_workspace"
  aerospace workspace "$target_workspace"
}

You can view my complete configs here: aerospace.toml and aerospace.sh.

# MacOS puts a quarantine on application files extracted from zip files
xattr -d com.apple.quarantine /Applications/VSCodium.app

VSCode is a popular code editor that can be customized with community extensions. These extensions can change how the editor works, but they’re limited. The deeper parts of VSCode, like its ElectronJS window system or internal code, are locked away from extensions on purpose.

So, if you want to fully customize VSCode without limits, you’ll need to edit the source code yourself and build your own version. Here’s how to get started:

# Clone the VSCode source code from GitHub
git clone git@github.com:microsoft/vscode.git

# Move into the project folder
cd vscode

# Install the required tools and dependencies
npm install

# Build the code and watch for changes as you edit
npm run watch

# Launch a debug version of your custom VSCode
./scripts/code.sh

This method works well! For example, I submitted a PR to add floating window support on macOS. But not every change gets accepted by the VSCode team at Microsoft. They can’t maintain every new feature, which makes sense.

Sometimes, the changes you want to make don’t fit with how VSCode is designed. Let me show you an example to explain this better.

By default, folding in VSCode looks like this:

Let’s say you want to tweak how folding works. Here’s a quick (but messy) fix I came up with:

--- a/src/vs/editor/contrib/folding/browser/syntaxRangeProvider.ts
+++ b/src/vs/editor/contrib/folding/browser/syntaxRangeProvider.ts
@@ -20,6 +20,8 @@ const foldingContext: FoldingContext = {
 
 const ID_SYNTAX_PROVIDER = 'syntax';
 
+export const FOLD_END_PATTERN = /^\s*\}|^\s*\]|^\s*\)|^\s*end/;
+
 export class SyntaxRangeProvider implements RangeProvider {
 
 	readonly id = ID_SYNTAX_PROVIDER;
@@ -73,6 +75,13 @@ function collectSyntaxRanges(providers: FoldingRangeProvider[], model: ITextMode
 				}
 				const nLines = model.getLineCount();
 				for (const r of ranges) {
+					if(r.end < nLines) {
+						let endLineContent = model.getLineContent(r.end + 1);
+						if(FOLD_END_PATTERN.test(endLineContent)) {
+							r.end = r.end + 1;
+						}
+					}
+
 					if (r.start > 0 && r.end > r.start && r.end <= nLines) {
 						rangeData.push({ start: r.start, end: r.end, rank: i, kind: r.kind });
 					}

This patch fixes the folding issue, and the result looks like this:

But here’s the catch: this is a hack. The VSCode team probably wouldn’t accept it as a PR because it’s not a clean, long-term solution.

The VSCode source code by default only lets you build a debug version called Code - OSS. This version is limited; it only runs on the computer where you built it.

For a fully working, shareable version, there’s a community project called VSCodium.
VSCodium takes the open-source VSCode code, removes Microsoft branding and telemetry, and adds patches to make it a complete, open-source alternative.

VSCodium uses a script (dev/build.sh) that grabs the VSCode source code, applies custom patches (from patches/*.patch), and builds the editor. Here’s how I built my own version:

# Clone the VSCodium project
git clone git@github.com:VSCodium/vscodium.git

# Check the stable version’s commit hash
cat ./vscodium/upstream/stable.json
# Note the commit hash—it’s the starting point for the patches

# Clone the VSCode source code
git clone git@github.com:microsoft/vscode.git

# Move into the VSCode folder
cd ./vscode

# Switch to the commit hash from stable.json
git checkout "<the commit hash>"

# Create a new branch for your changes
git checkout -b your_branch

# Make your edits and test them here

# Save your changes as a patch file
git diff > ../vscodium/patches/your_patch.patch

# Move back to the VSCodium folder
cd ../vscodium

# Install a required tool (if you’re on macOS)
brew install cmake

# Build the editor (takes 5-10 minutes)
./dev/build.sh

# Find your finished app
ls ./VSCode-darwin-arm64/VSCodium.app

Other Options

• You can build my VSCodium fork, which includes the folding fix and floating window support.
  • To enable floating window, add this snippet to your settings.json:

      "window.workspacesOverlay": {
          "enabled": true,
          "alwaysOnTop": false,
          "hotKey": "Control+Enter",
          "snapMode": "bottom"
      }
    

• Or grab the pre-built version here and run:

    # MacOS puts a quarantine on application files extracted from zip files
    xattr -d com.apple.quarantine /Applications/VSCodium.app
  

Updated Jan 27, 2025: Now supports Bun.

The default REPL is hard to access for a detached NodeJS process.

Even if you gain access to it:

• It can’t be accessed by multiple developers at once.
• Hitting <Ctrl+C> terminates the process; far from ideal!

But there is a neat solution. We can leverage the built-in node:repl and node:net modules.

import repl from "node:repl";
import net, { Socket } from "node:net";
import readline from "node:readline";
import util from "node:util";
import process from "node:process";

const REPL_PORT = 5001;
const replContextAdditions: Record<string, any> = {};
const isBun = !!(process.versions as any).bun;

const server = net.createServer((socket: Socket) => {
  if (isBun) {
    handleBunRepl(socket);
  } else {
    handleNodeRepl(socket);
  }
});

server.on("error", (err: Error) => {
  console.error("Server error:", err);
});

server.listen(REPL_PORT, () => {
  console.log(`REPL server running on port ${REPL_PORT} (${isBun ? "Bun" : "Node.js"})`);
});

export function addToRepl(obj: Record<string, any>) {
  Object.assign(replContextAdditions, obj);
}

function handleNodeRepl(socket: Socket) {
  const replServer = repl.start({
    prompt: "> ",
    input: socket,
    output: socket,
    terminal: true,
    preview: false,
    useColors: true,
    useGlobal: false,
  });

  replServer.on("exit", () => {
    socket.end();
  });

  Object.assign(replServer.context, replContextAdditions);
}

function handleBunRepl(socket: Socket) {
  const context = { ...replContextAdditions };

  const rl = readline.createInterface({
    input: socket,
    output: socket,
    terminal: true,
    prompt: "> ",
    completer: (line: string) => compl(line, context),
  });

  rl.on("line", (line) => {
    const trimmed = line.trim();
    if (!trimmed) return rl.prompt();

    try {
      // Basic eval implementation for Bun
      const result = new Function("context", `with(context) { return (${trimmed}) }`)(context);
      socket.write(util.inspect(result, { colors: true }) + "\n");
    } catch (err) {
      socket.write(util.inspect(err, { colors: true }) + "\n");
    }
    rl.prompt();
  });

  rl.on("close", () => socket.end());
  socket.on("end", () => rl.close());

  rl.prompt();
}

function compl(line: string, context: any) {
  try {
    const ctx = { ...globalThis, ...context };
    const match = line.match(/^((?:.*[ .(\[])?)([^ .(\[]*)$/);
    if (!match) return [[], line];

    const [, expr, last] = match;
    const query = expr.trim().replace(/[. ]+$/, "");
    const target = query ? new Function("ctx", `with(ctx) { return ${query} }`)(ctx) : ctx;

    if (target == null) return [[], line];

    const keys = new Set<string>();
    for (let o = target; o; o = Object.getPrototypeOf(o)) {
      Object.getOwnPropertyNames(o).forEach(k => keys.add(k));
    }

    const hits = Array.from(keys).filter(k => k.startsWith(last));
    return [hits.map(h => expr + h), line];
  } catch {
    return [[], line];
  }
}

Run the repl_server.ts and manually add application objects to the context.

// main.ts
import { addToRepl } from "./repl_server.ts";

let app = { todo: 'application' };
addToRepl({ app });

To connect to the REPL, use the following script:

// repl_client.ts
import net from 'node:net'
import process from "node:process";

let sock = net.connect(5001)

process.stdin.pipe(sock)
sock.pipe(process.stdout)

sock.on('connect', function () {
  process.stdin.resume();
  process.stdin.setRawMode(true)
})

sock.on('close', function done () {
  process.stdin.setRawMode(false)
  process.stdin.pause()
  sock.removeListener('close', done)
})

process.stdin.on('end', function () {
  sock.destroy()
  console.log()
})

process.stdin.on('data', function (b) {
  if (b.length === 1 && b[0] === 4) {
    process.stdin.emit('end')
  }
})

The package.json may look like this:

{
  "type": "module",
  "scripts": {
    "start": "node src/main.ts",
    "repl": "node ./src/repl_client.ts"
  }
}

ta-da!

_{Credits to gist.github.com/TooTallNate/2209310}

Caddy is an easy-to-configure reverse proxy which enables HTTPS by default.
The TLS certificates are issued by Let’s Encrypt, and caddy automatically renews them for you.

To install it, follow the documentation; here is the debian installation section:

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy

Caddy is installed as a new service, which continues to run even after you reboot your server.

# Use the service command to manage the "caddy" service.
service caddy status 
service caddy restart

# Or systemctl, if you prefer that option.
systemctl status caddy

The service, by default, points to the /etc/caddy/Caddyfile; create one if it doesn’t exist.

touch /etc/caddy/Caddyfile

You need to have a domain with an A record pointing to your server’s IP address.
Here’s how to do that on Cloudflare, Namecheap, or GoDaddy.

Assuming your local HTTP based service is running on port 8080 …

# For example, the comment section on this blog is handled by remark42.
# Here is the relevant portion of my docker-compose.yml
services:
  remark:
    image: umputun/remark42:latest
    container_name: "remark"
    restart: always
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      # redacted
    volumes:
      - /var/lib/remark:/srv/var

Update the Caddyfile and restart the service.

# /etc/caddy/Caddyfile
yourdomain.com {
  reverse_proxy * 127.0.0.1:8080
}

service caddy restart

After a minute or so, you should be able to open https://yourdomain.com using a web browser.

To see the service logs, use the journalctl command.

journalctl -f -u caddy

Here is more a complex example.

myblog.com {
  # serve the html/css/js files from /root/app
  root * /root/app
  file_server

  # Api calls go to 3001 on localhost
  reverse_proxy /api/* 127.0.0.1:3001
}

# comment section on a subdomain
remark.myblog.com {
  reverse_proxy * 127.0.0.1:8080
}

See the Common Patterns section of the docs for more advanced features.