frame

agent
Guvenlik Denetimi
Uyari
Health Uyari
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 6 GitHub stars
Code Gecti
  • Code scan — Scanned 12 files during light audit, no dangerous patterns found
Permissions Gecti
  • Permissions — No dangerous permissions requested

Bu listing icin henuz AI raporu yok.

SUMMARY

an AI harness - zsh · ghostty · neovim · claude code

README.md

frame

macos
linux

frame - an AI harness built on zsh, ghostty, neovim, and claude code

frame wt booting a worktree into neovim with a Claude buffer
website · youtube demo

Table of Contents

What Frame does

  • Treat Neovim like a multiplexer.
  • A frame is a terminal running one Neovim instance provisioned with a named RPC socket so other frames and the CLI can drive it.
  • Each frame has one Claude buffer.
  • The frame CLI injects lua and puts a message broker in front of claude.
  • frames join the pool and become discoverable via frame ls
  • In addition to claude you will typically have services like Vite and or binary backend service running in their own buffers. Frame manages the port assignments so you can stand up a frame per worktree/Topic.
  • frames are self contained and disposable: once a topic is merged (frame merge;:FrameMerge) and, when you're ready, pushed (frame push;:FramePush), tear the frame down (frame wt -d;:FrameDown). Merge and teardown are separate guarded steps to ensure a clean delivery back to the primary branch before frame disassembly.
  • The default behavior is for the claude session to expire with the frame but complete context can be passed from frame to frame with frame wt $TOPIC --from=SRC_FRAME.
  • Ghostty is the intended terminal — window focus and spawn-into-tabs use its scripting — but a frame still runs in other terminals.
command what it does
frame wt TOPIC [--from SRC_FRAME] create/reuse a branch and worktree, boot it. --from instructs SRC_FRAME claude to teardown and then context is transferred forward
frame wt boot the worktree you're already in
frame wt -d [TOPIC] tear down a frame (default: the current one)
frame shell TOPIC a frame in the current dir with no branch — just the claude and local buffers
frame shell -C DIR TOPIC the same, in DIR (any dir — nothing is written into it)
frame shell [TOPIC] --find "WORDS" find a past claude session by what you typed in it, pick one, and resume it in the dir it ran in (--resume ID for a known id)
frame shell [TOPIC] --recent browse your most recent claude sessions (first message of each), pick one, and resume it (worktree sessions are left out)
frame ls list every live frame across projects
frame merge [TOPIC] merge a topic branch into the primary branch
frame push push the primary branch to origin
frame claude TEXT… ask this frame's claude, block for the answer
frame req NAME/TOPIC TEXT… ask another frame's claude (async)
frame inbox read replies routed back to you
frame services up bring up the shared services stack
frame focus [TOPIC] raise a frame's window
frame yolo on|off toggle --dangerously-skip-permissions everywhere
frame swarm [off|1|2] how much frame context each frame's claude gets — 0 off · 1 aware · 2 ask (starts off)
frame kv [get|set|unset …] how far each frame's claude goes on its own (autocommit, merge/push/deploy on merge) plus your own keys; per frame, project, user

worktree is a synonym for wt; list for ls.
Not shown here: spawn,
deliver, reply, view, status, name, notify, notifications, silence, and every
--flag — see frame --help (full usage).

Other Features

  • Vim/Claude integration - :FrameClaude allows for quick conversations and code analysis
  • Shared Services - Databases and Object Stores can be stood up once in the frame repo and share their services between all your projects
  • OS-level Notifications (macOS) - a banner when a frame has Completed its task, Needs Attention, or is Blocked — with the Frame icon and click-to-focus. On Linux the same pings arrive via notify-send (install libnotify), minus the icon and click-to-focus; see Platform support.
  • swarm - uses the SessionStart hook to inform all frame claudes that they are frames and how to find their siblings. See Swarm: telling agents they're in a frame for the per-level breakdown.
  • shell - a thin (non worktree) frame for raw claude work
  • YOLO mode to globally enable/disable --dangerously-skip-permissions. (Note: once changed, only newly booted frames follow the new setting.)

Getting Started

Prerequisites

  • zsh
  • git ≥ 2.5
  • neovim (no plugins required) — validated with both a minimalist bare Vim setup and LazyVim
  • claude (Claude Code CLI)
  • docker with the compose v2 plugin (if running shared services)
  • macOS + OrbStack (any docker provider works if already running; auto-start is OrbStack-only) — Linux runs the core workflow, see Platform support
  • curl, lsof

Platform support

macOS is the primary target, but the core workflow is portable: worktrees, the
nvim layout, the claude broker (frame claude / frame req / frame inbox),
merge/teardown, port assignment, and the shared services all work on Linux.
What doesn't — the window and notification chrome is built on macOS
Automation:

  • frame focus and frame spawn are macOS-only. Window raising and
    worker-tab spawning go through AppleScript/System Events — Linux Ghostty
    doesn't carry that dictionary. Both refuse with a clear error; boot workers
    by hand in another terminal instead.
  • Banners fall back to notify-send (install libnotify) — you get the
    Completed/Attention/Blocked pings, minus the Frame icon and click-to-focus.
    frame notifications init (the banner-app build) is macOS-only.
  • Docker auto-start is OrbStack-only. On Linux, start your docker daemon
    before booting a frame that needs the shared services; frame wt errors
    with instructions if it isn't running.

The test suite runs on both macOS and Linux in CI; the macOS-only surfaces
skip on Linux, where their refusal paths are tested instead.

Install Frame

# 1. Clone Frame
git clone https://github.com/scoop206/frame.git

# 2. Enter the repo
cd frame

# 3. Put frame on your PATH (this line persists it in ~/.zshrc)
echo "export PATH=\"$PWD/bin:\$PATH\"" >> ~/.zshrc
source ~/.zshrc

# 4. Verify
frame --help

Onboarding a project

Scaffold a project's Frame config and boot your first frame in four steps.

1. Go to your project.

cd $YOUR_PROJECT

2. Scaffold the Frame config.

frame init

This writes two things:

  • .frame/config.sh — the project config
  • .frame/local/ — gitignored, for personal overrides

Project types. --type picks what init scaffolds. A project has one
base (default generic) and any number of layers; the flag repeats to
stack them: frame init --type astrojs --type cloudflare. frame init --types
lists what's available:

type kind adds
generic base the default config.sh: BUFFERS=(claude local)
astrojs base an Astro config.sh (a vite buffer at the repo root, each worktree with its own node_modules), starter Astro files, build-output .gitignore lines
cloudflare layer WT_LINKS+=(.dev.vars), so every worktree links Cloudflare's local secrets from the primary checkout, and .dev.vars in .gitignore

The generated config.sh is deliberately bare; every key is described under
config.sh. Init never overwrites a file. Re-running it with a new
layer appends that layer's lines to your existing config.sh; a new base only
applies to a project that has no config.sh yet.

Your own types. A type is a folder of plain files; init copies them and
runs nothing. Put yours in ~/.config/frame/types/<name>/. A folder with the
same name as a built-in replaces it. The built-ins in
templates/types/ show the layout: generic and astrojs
are bases, cloudflare is a layer. Copying one is the quickest start:

mkdir -p ~/.config/frame/types
cp -R path/to/frame/templates/types/generic ~/.config/frame/types/mytype
frame init --types   # mytype is listed as (yours)
file what it is
type required: kind=base or kind=layer, and description=… for frame init --types
config.sh base: the whole config.sh. {{NAME}} becomes the project name
config.layer.sh layer: lines appended to config.sh, once
files/ copied into the project root, each file only if it isn't there yet
gitignore lines appended to .gitignore once, under a # frame:<name> marker

Anything that has to happen at runtime belongs in the generated config.sh
(a stack_up() function, say), not in the type.

3. (Optional) Change which buffers your frames open.
frame init already scaffolds a working default — BUFFERS=(claude local) — so you can skip straight
to booting a frame. Edit .frame/config.sh only if you want different buffers
(e.g. add vite or a backend server).

$EDITOR .frame/config.sh

4. Boot a topic/worktree frame. Neovim fires up with the Claude buffer in front.

frame wt scratch-topic

See How a project plugs in for the full config.

Worktrees

Worktrees are created beside the primary checkout as ../_<name>-<topic>.
The leading underscore marks them as frame-managed and keeps them sorted
together in the parent directory; frame also parses the name to infer the
topic when you run frame wt (or frame wt -d) from inside one.

frame wt TOPIC is the typical entrypoint.

For example:
This starts neovim w/ custom layout which is usually 4 buffers:

  • claude - starts claude-code
  • vite - cd web && npm run dev
  • server - cargo run -p $PROJECT-server
  • local - bare terminal

The ghostty window will now be named $REPO [ $TOPIC :PORT ]
You can see vite's rendered web app at http://localhost:PORT

What a worktree doesn't get from git

A new worktree only has committed files, so gitignored ones (.env secrets,
Cloudflare's .dev.vars, installed dependencies) are missing from it. The
WT_LINKS key in config.sh lists paths, relative to the repo root, that every
worktree shares with the primary checkout: on each frame wt boot, frame
symlinks each one in from the primary. It skips a path the worktree already has
(a real file wins) and one the primary doesn't have. Unset, it defaults to
(.env web/node_modules); WT_LINKS=() turns linking off.

These are links, not copies: editing a linked .env from inside a worktree
changes the primary's file, and so every frame's. For node_modules that also
means one shared set of dependencies and build caches, which is why the astrojs
type gives each worktree its own copy instead (frame_clone_node_modules).

Vim commands

When frame instantiates the nvim instance it injects these user commands
(defined in layouts/session.lua), available from any buffer in the session:

command action
:FrameStatus TEXT… append "- TEXT" to the window title's status suffix (no TEXT clears it)
:FrameName copy this frame's name/topic to the system clipboard — the handle to paste into another frame's frame req/focus
:FrameSilence [off] silence this frame's banners (no arg, or 'on'); pass 'off' to unsilence
:FrameQuit quit the session only — worktree and branch stay for a later frame wt TOPIC
:FrameDown tear down the whole frame: quit nvim, remove the worktree, delete the branch
:FrameDown! force teardown — discard uncommitted changes and unmerged commits
:FrameMerge merge this frame's branch into the primary branch (same safeguards as frame merge)
:FrameMerge! merge, then push the primary branch to origin (mirrors frame merge --push)
:FramePush push the primary branch to origin (same safeguards as frame push)
:FrameKv list the frame kv settings: value + the layer it came from
:FrameKvGet KEY print one setting
:FrameKvSet [--project|--user] KEY VALUE set a setting (default: this frame only); tab-completes keys and values
:FrameKvUnset [--project|--user] KEY drop a setting from that layer so the next one down shows through
:FrameKvDescribe [KEY] what a setting means: type, default, where it's declared (all of them when bare)
:[range]FrameClaude [Q] open this frame's claude terminal; with a [range] paste the line/selection as context; with a question Q submit it

Asking claude from the editor — :FrameClaude

:FrameClaude is the in-editor way to reach this frame's claude — the same
single conversation frame claude talks to. It opens that claude's live
terminal in a far-right vertical split and drops you into Terminal-mode at the
prompt. Its behavior is keyed on two things: a range (attaches context) and
a question (submits).

  • Bare :FrameClaude (no range, no question) just opens the prompt — your
    cursor lands in claude's terminal, nothing is sent.
  • :'<,'>FrameClaude (a range or visual selection, no question) pastes the
    file:line plus the fenced source into the prompt and leaves it there for you
    to type your question and submit.
  • :FrameClaude <question> attaches the current line (or the
    range/selection) as context and submits it right away.

Unlike frame claude and frame req, this is a direct write into claude's
terminal, not a brokered turn — it interleaves with an in-flight turn exactly as
manual typing would, rather than queuing behind it.

PostToolUse Hook

The naive approach for this is to have both neovim and claude modifying the same file on disk.
So any mods by claude will cause you, the editor, to have to reload the file.
With frame's PostToolUse hook in place, claude will send the edit event to your neovim instance, allowing your buffer to update automatically (in general no need to reload).
It's not perfect, and if you are making your own edits at the same time then you might need to reload from disk (as your buffer will now be considered 'dirty').
A good rule of thumb is to save often. That should mitigate the chance of a clobber happening if you and claude are modding at the same time.

Frame Merge

When a topic is done, frame merge [TOPIC] — or :FrameMerge from inside the
frame — merges its branch into the primary branch from wherever you are,
pushing to origin only when you ask (--push, or :FrameMerge!). The primary
branch is whatever the primary checkout has checked out — main and master
projects both work, nothing is hardcoded. What makes it safe is the guardrails,
in the order they run:

  • Primary must be clean — refuses if the primary worktree has uncommitted
    tracked changes on the primary branch.
  • Uncommitted topic work is flagged — only the committed branch tip gets
    merged, so a warning calls out anything uncommitted in the topic worktree
    that would be silently left out.
  • No guessing on divergence — the primary branch is brought level with
    origin first (fast-forward only); if it and origin have diverged, it stops
    and leaves the reconciliation to you.
  • Conflicts stop cleanly — on a merge conflict it halts and prints the
    exact merge --abort to back out.
  • Push is opt-in — nothing touches origin unless you pass --push.

Pushing later is its own step: frame push — or :FramePush from inside the
frame — publishes the primary branch to origin, with its own rails (refuses
when the primary branch is behind origin or has diverged; already level is a
clean no-op). Worktree and branch cleanup stays with frame wt -d (below).

Frame Removal

Teardown always runs from within the project's git tree — a frame worktree, the
primary checkout, or another frame of the same project. Where you're standing
decides whether you name the topic.

If you're in the worktree you want to remove, frame reads the topic from
your location:

  • frame wt -d
  • or :FrameDown from inside the frame's nvim

From anywhere else in the project — the primary checkout, or another
worktree — name the topic (frame ls helps you find it):

  • frame wt -d TOPIC

Teardown Safeguards

Teardown refuses when either of these is true:

  • the worktree has uncommitted changes, or
  • the branch has commits not yet on the primary branch.

Clear it by merging first (frame merge), or force through with
frame wt -d -f [TOPIC] / :FrameDown!.

These checks run before nvim is quit, so a refusal never leaves you
editor-less. Reaper output lands in /tmp/frame/<name>-<topic>.teardown.log.

Notifications

Fixing the banner badge

At first the badge is a generic AppleScript badge — clicking it opens Script
Editor instead of focusing your frame. Things work fine in this state, but here
are the extra steps to get the badge right:

brew install terminal-notifier

Then build the Frame app icon for the banner with:

frame notifications init

You should be prompted to allow for Frame to notify:

  • System Settings → Notifications → Frame → Allow.

You can send a test notification with:

frame notify

If the new badge is still not working you can also try (they will respawn):

killall usernoted NotificationCenter

If the badge remains stuck, or continues to display an outdated icon after the
art has changed, this indicates an icon-cache issue rather than a notifier
problem. Refer to
docs/fixing-stuck-banner-badge.md for
detailed resolution steps.

Inbox filtering

When you send a frame req, Frame prints a token (token: frame/topic#id) — a
unique id for that request. Your inbox is shared: replies from every
frame req you've fired land there together, so reading in order can't guarantee
you're looking at the answer to a specific request.

Pass --for <token> to frame inbox to retrieve only the reply for that request:

frame inbox --for frame/comms2#r7        # just that one answer

--for is repeatable, which makes it a fan-in barrier for correlated fan-out:
fire N reqs, capture each token: line, then wait for exactly those N answers —
unrelated mail landing mid-wait is left behind, not counted:

frame inbox --wait --for $t1 --for $t2   # blocks until both r1 and r2 arrive

Swarm: telling agents they're in a frame

By default a frame's Claude doesn't know it's in a frame. frame swarm changes that
by injecting a short block at every session start.

frame swarm             # show the current level
frame swarm LEVEL       # set the level per table below
level mode agent guidance
0 off nothing (the default)
1 aware who it is — NAME/TOPIC + its dev-server URL, read from the frame's own environment (present only inside a real frame); and the frame-safe way to act — merge/tear down via frame merge / frame wt -d (not raw git), local merges are the agent's but pushing to origin stays with you, subagents it waits on run in the foreground, and a request from a sibling gets an answer, not an action. No sibling coordination.
2 ask level 1 plus a bounded recipe for asking sibling frames read-only questions (frame req → frame inbox --wait --for, with a per-turn budget and a 2-hop limit). Find who to ask with frame ls.
3 fan-out the ambitious top — lead-frame fan-out/gather. Not built yet, so 2 is the current ceiling: selecting 3 is refused and points you back at 2.

Extending the swarm instructions

Define swarm_context() in one of the config files below and its output is
appended after the built-in core — a natural home for a one-line "this frame
owns X". Where you define it sets the scope; later scopes override earlier ones,
and the core safety rules are never overridable, so an append can only add,
never drop a rule.

path scope
~/.config/frame/config.sh machine-wide — every project
.frame/config.sh this project, committed (shared with team)
.frame/local/config.sh this project, personal (gitignored)
# .frame/config.sh
swarm_context() {
  echo "This frame owns pactduo-infra — the shared pg (5432) + minio (9000)."
}

Agent autonomy settings: frame kv

frame kv holds the settings that tell a frame's claude how far to carry its
work without asking. The git keys default to false, meaning you drive commits,
merges and pushes yourself; spawn_frames defaults to true:

key when true
autocommit the agent commits each finished, working step without asking
merge_on_commit …and then runs frame merge into the primary branch
push_on_merge frame merge pushes to origin itself, as if --push were given (--no-push skips it once)
deploy_on_merge frame merge ends by telling the agent to run the project's deploy
spawn_frames work for another repo goes to that repo's frame (frame ls); if it has none, the agent frame spawn wts one without asking (false: it asks first)
frame kv                                   # every key, its value, and which layer set it
frame kv get push_on_merge
frame kv set push_on_merge true            # this frame only
frame kv set --project autocommit true     # every frame of this project
frame kv set --user merge_on_commit true   # every project on this machine
frame kv unset push_on_merge               # fall back to the next layer
frame kv describe push_on_merge            # what it means, its type, default, and origin
frame kv --of comms2                       # another live frame's kv (read-only)

In nvim: :FrameKv, :FrameKvGet, :FrameKvSet, :FrameKvUnset, :FrameKvDescribe.

Layers, first hit wins:

layer where it lives
frame the frame's own nvim session, in memory (worktree and shell frames alike)
project <primary checkout>/.frame/local/kv (gitignored, so it never blocks frame merge)
user ~/.config/frame/kv
default the key's declared default (see Your own keys)

The frame layer lives inside the frame, so it ends with the frame and never
leaves stale files behind. The trade-off is that it only exists while the frame
is running:

  • When a frame is down, its frame layer reads as empty (lookups fall through to
    project, user and default) and setting it is refused.
  • Quitting or crashing a frame loses its frame-level settings and notes, and a
    rebooted frame starts clean. frame wt --from carries them into the new frame.
  • frame merge of a frame that isn't running can't see its own settings. If
    that leaves push_on_merge or deploy_on_merge on from a shared layer, the
    merge says so.

The shared layers are files rather than environment variables on purpose. A
process's environment is fixed when it starts, so an export never reaches a
claude that's already running. A file is read at the moment it's needed, so a
change takes effect mid-session. The swarm block (level 1 and up) shows the
agent the values at session start and tells it to re-check frame kv get
before it commits or merges.

The settings are yours, not the agent's. From inside claude, frame kv writes
only the agent's own frame layer (--project and --user are refused), set
only accepts false, and unset is refused, so an agent can hold itself back
but can't give itself more room. String keys (below) can't be set by an agent at
all, since there's no "safer" direction for a string. This guards against
well-meaning drift; it isn't a security boundary.

Your own keys

Beyond the built-ins, you can declare keys for your own workflow boundaries or
your project's own attributes. Frame stores them and tells the agent about them;
what they mean is up to you, your agents, and your hooks, which read them with
frame kv get KEY. Declarations live in files in the same format as
kv.defaults:

declared in committed? applies to
<primary checkout>/.frame/kv.defaults yes every frame of the project
~/.config/frame/kv.defaults n/a every project on this machine

Each declaration is a key=default line with its meaning in the comment block
right above it. The first comment line is the one-line description the agent
sees at session start; any further lines show up in frame kv describe:

# .frame/kv.defaults
# Run the e2e suite before each commit.
# It takes ~4 minutes; skip it for docs-only changes.
run_e2e=false

# Language the agent writes review comments in.
review_lang=en
  • Type comes from the default: true/false makes the key boolean (only
    true/false accepted), anything else makes it a string. Name boolean keys
    so that true grants the agent something and false holds it back, because
    that's the direction the agent guard allows.
  • Values go in the same layers as the built-ins (frame kv set [--project|--user] KEY VALUE). The declared default is the bottom layer.
  • Clashes: a declaration of a built-in key is ignored with a warning (change
    its value with frame kv set instead). If the project and the user declare
    the same key, the project's declaration wins.
  • Keys are lowercase letters, digits and _, starting with a letter. A line
    that isn't a declaration is skipped with a warning in frame kv.
  • Project declarations are read from the primary checkout, so a key added on a
    topic branch takes effect once it's merged.
  • The swarm block lists each custom key's value and one-line description, so the
    agent knows it exists and what it means.

Agent notes

Any key that isn't declared belongs to the agent. It can set and unset such keys
freely, on its own frame only, to keep state about its work:

frame kv set ticket ENG-412      # from inside claude
frame kv get ticket              # anyone, from that frame
  • Notes live in the frame's session beside its frame-level settings, so they
    go away with the frame.
  • frame kv lists them with FROM frame (agent).
  • They're only looked up for undeclared keys, so a note can never override a
    setting. If you later declare a key an agent had used as a note, the
    declaration wins and frame kv warns that the note is ignored.
  • You can edit or unset an existing note from your side. You can't create one:
    an undeclared key from you is still treated as a typo.
  • The swarm block tells the agent it may keep notes, and shows the current ones
    at session start, so a resumed session picks its state back up.
  • frame view [TOPIC] shows a frame's notes and any settings that differ from
    their defaults.
  • Any frame can read another live frame's kv, notes included, with
    frame kv --of TOPIC (or NAME/TOPIC; resolved like frame req). It works
    with get KEY and describe too, and it's read-only: set and unset are
    refused.

How a project plugs in

Everything project-side lives under one .frame/ directory:

path committed? contents
.frame/config.sh yes the project's config — keys and hooks, detailed below
.frame/kv.defaults yes the project's own frame kv keys (Your own keys)
.frame/local/ never (gitignored) personal overrides — a config.sh here wins

Claude hooks

Every frame starts its Claude with
--settings ~/.local/share/frame/claude-hooks.json, a copy of frame's
claude/hooks.json that frame refreshes on boot whenever it changes. The hooks
plug Claude into frame's lifecycle signaling:

  • Stop → frame notify (banner + "waiting" title) and frame reply (route a reply to a requester)
  • UserPromptSubmit → frame status --prompt ("working" title + turn-start stamp)
  • Notification → frame notify --blocked ("blocked" title + banner)
  • SessionStart → frame swarm --context (frame-awareness, when swarm ≥ 1)
  • PostToolUse → frame reload-editor (reloads the just-edited file into this frame's nvim buffer, when it's open)

These merge with the project's own .claude/settings.json, if it has one.

Examples

Worked, copyable integrations live in examples/ — each a
complete .frame/config.sh like the one frame init writes:

  • barebones/ — the minimum: a config.sh with just BUFFERS
  • astrojs/ — a root-dir npm app (an Astro static site): just the vite buffer, no backend
  • standard-web/ — a server + vite app on the shared postgres/minio
  • sidecar/ — everything above, plus its own project-unique container

Copy the closest one (or run frame init and edit) and the project is fully
wired; there's nothing else to add. See examples/README.md
for the field-by-field walkthrough.

config.sh

The keys a project sets:

key required purpose
NAME no project name; window titles, worktree dirs, and frame addresses derive from it. Defaults to the primary checkout's directory name — so it follows a repo rename. Set it only to pin a name that outlives the directory
BUFFERS=(…) yes which buffers each frame opens, e.g. (claude local) — see Buffer Definitions
SERVER_CMD no the command that starts your dev server; runs verbatim in the server buffer type and must bind $PORT
VITE_DIR no the directory the vite buffer runs in (default web; set . for a root-dir npm app, e.g. Astro)
WT_LINKS=(…) no gitignored paths every worktree symlinks from the primary checkout (default (.env web/node_modules)) — see What a worktree doesn't get from git
API_PORT VITE_PORT HMR_PORT PORT_PREFIX no port configuration — see Port assignment below

Hooks:

  • stack_up() — bring up whatever the dev stack needs. Runs on every frame wt
    boot, so keep it idempotent. Shared postgres/minio come from
    frame_services_up / ensure_pg_db / ensure_minio_bucket; only
    project-unique containers belong in the project's own compose file — pin
    those with --project-directory "$MAIN_WT" so every frame shares one
    instance instead of spawning a per-worktree compose project. For an npm
    project, frame_clone_node_modules gives each worktree its own
    copy-on-write node_modules (an APFS clonefile where supported, a plain copy
    otherwise; either way per-frame dep-optimizer caches stop fighting). It
    first brings the primary's deps up to date (installs there when its
    node_modules is missing or out of step with its package.json, lockfile or
    node version), so a worktree never inherits a stale tree.
  • app_env() — export the vars pointing the app at what Frame set up: the
    shared services (DATABASE_URL, S3 endpoint, …) and, if your app reads its
    port under a name other than the PORT frame tracks (see buffers.json),
    a re-export of it here (e.g. export SERVICE_PORT="$PORT"). Exported vars
    win over .env (dotenvy never overrides the environment).
  • merge_epilog() — runs after a successful frame merge, as
    merge_epilog TOPIC PUSHED ($2 is true when it pushed). Off unless you
    define it; a common use is reminding whoever merged to tear the frame down.
    Define it in ~/.config/frame/config.sh to apply to every project.

Port assignment

Frames run in parallel, so two worktrees of the same project can't share a port.
Rather than assign fixed ports, the config declares base ports and frame
finds a free one at each boot: on frame wt it scans upward from each base
until it hits a port nothing is listening on. The first frame lands on the bases
themselves (3000 / 5173 / 24678), the next worktree one higher (3001 /
5174 / 24679), and so on.

You set the bases (all optional — omit them for a project with no web server and
nothing is scanned or exported):

key default base port for
API_PORT 3000 your server buffer's dev server
VITE_PORT 5173 the vite dev server
HMR_PORT 24678 vite's HMR websocket
PORT_PREFIX NAME, upper-cased, non-alphanumerics → _ prefixes the legacy per-project vars below

Frame exports the ports it actually picked; your app and vite.config.* read
them:

var example what it is
PORT 3001 the chosen server port — SERVER_CMD must bind this
FRAME_API_PORT 3001 the server port again, under frame's own name
FRAME_VITE_PORT 5174 the chosen vite port
FRAME_HMR_PORT 24679 the chosen HMR websocket port
<PREFIX>_API_PORT FLIPNEM_API_PORT=3001 the server port, under your project prefix
<PREFIX>_VITE_PORT FLIPNEM_VITE_PORT=5174 the vite port, under your project prefix
<PREFIX>_HMR_PORT FLIPNEM_HMR_PORT=24679 the HMR port, under your project prefix

PORT is the generic handle the server buffer binds; the FRAME_* vars are
the names to read from vite.config.* and friends — they never change, no
matter what the project or its directory is called. The <PREFIX>_* aliases
carry the same values for app code already reading project-prefixed names;
that prefix is baked into committed code, so if you rely on it, pin
PORT_PREFIX in config.sh — the derived default follows a directory rename
and would silently stop matching what your code reads. If your app reads its
port under yet another name, re-export it in app_env() (e.g. export SERVICE_PORT="$PORT").

Buffer Definitions

Every buffer type a project can instantiate needs to be in the buffers.json Frame registry.

Per entry:

field meaning
name buffer name (targeted by BUFFERS)
mode durable (default) runs the command then drops to a shell on exit; prefill types the command at the prompt without running it; bare is an empty shell
command the command the buffer runs — ${VAR}s replaced from the boot environment
dir subdirectory to run in — same ${VAR} replacement (e.g. vite runs in ${VITE_DIR}); resolving empty → the worktree root
env vars the command reads — a declared contract; frame warns at boot if unset
focus land here after boot

Shared (Centralized) Services

The centralized postgres/minio belong to frame itself
(services/docker-compose.yml), not to any
project — one postgres on :5432 and one minio on :9000/:9001 serve every
project. There is no per-project setup.

  • First boot: nothing to do in advance. frame wt runs the project's
    stack_up(), whose frame_services_up call starts the containers
    (auto-starting OrbStack if docker isn't up) and waits for them to be healthy.
    Whichever frame boots first brings the stack up for everyone.
  • Manually: frame services up / frame services down / frame services ps
    from anywhere.
  • Multi-tenancy: each project claims its slice in stack_up() — helper
    functions in lib/helpers.sh create roles/databases/buckets idempotently.
    ensure_pg_db NAME creates a role + database owned by that role (so one
    project's tests can't touch another's data), ensure_minio_bucket BUCKET
    creates its bucket. Standard ports, no per-project offsets.
  • Data lives in named docker volumes (pgdata, miniodata) and survives
    frame services down.

Service credentials

The stack boots with intentional dev-only defaults — frame/devpassword on
postgres, minioadmin/minioadmin on minio — and both services bind to
127.0.0.1 only, so nothing is reachable from the network. To use your own
credentials without editing the checked-in compose file, export overrides in
the machine-wide config (~/.config/frame/config.sh):

export FRAME_PG_USER=frame            # postgres superuser
export FRAME_PG_PASSWORD=…
export FRAME_MINIO_USER=…             # minio root
export FRAME_MINIO_PASSWORD=…

Compose interpolates these wherever the stack comes up (frame wt via
stack_up(), or frame services up); unset, the defaults apply.

Two things to know:

  • Postgres applies FRAME_PG_PASSWORD only when the pgdata volume is
    first created.
    Set overrides before your first boot; changing them later
    leaves the existing cluster on its old password (reset with
    frame services down && docker volume rm frame_pgdata). Minio picks up new
    root credentials on the next restart.
  • These are the admin credentials. Your app connects as its per-project
    role from ensure_pg_db NAME [PASSWORD] (default devpassword) — pass your
    own password there and put the same one in app_env()'s DATABASE_URL.

License

MIT

Yorumlar (0)

Sonuc bulunamadi