frame
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.
an AI harness - zsh · ghostty · neovim · claude code
frame
Table of Contents
- What Frame does
- Other Features
- Getting Started
- Worktrees
- Vim commands
- Frame Merge
- Frame Removal
- Notifications
- Swarm: telling agents they're in a frame
- Agent autonomy settings: frame kv
- How a project plugs in
- Buffer Definitions
- Shared (Centralized) Services
- License
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 -
:FrameClaudeallows 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(installlibnotify), 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 focusandframe spawnare 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(installlibnotify) — 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 wterrors
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 intemplates/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. TheWT_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 thefile:lineplus 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
exactmerge --abortto 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
:FrameDownfrom 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 withframe 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 everyframe 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 --fromcarries them into the new frame. frame mergeof a frame that isn't running can't see its own settings. If
that leavespush_on_mergeordeploy_on_mergeon 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 withframe kv get KEY. Declarations live in files in the same format askv.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/falsemakes the key boolean (onlytrue/falseaccepted), anything else makes it a string. Name boolean keys
so thattruegrants the agent something andfalseholds 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 withframe kv setinstead). 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 inframe 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 kvlists them with FROMframe (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 andframe kvwarns 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(orNAME/TOPIC; resolved likeframe req). It works
withget KEYanddescribetoo, and it's read-only:setandunsetare
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'sclaude/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) andframe 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: aconfig.shwith justBUFFERSastrojs/— a root-dir npm app (an Astro static site): just the vite buffer, no backendstandard-web/— a server + vite app on the shared postgres/miniosidecar/— 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 everyframe wt
boot, so keep it idempotent. Shared postgres/minio come fromframe_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_modulesgives each worktree its own
copy-on-writenode_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 itsnode_modulesis 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 thePORTframe tracks (seebuffers.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 successfulframe merge, asmerge_epilog TOPIC PUSHED($2istruewhen 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.shto 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, pinPORT_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 wtruns the project'sstack_up(), whoseframe_services_upcall 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 inlib/helpers.shcreate roles/databases/buckets idempotently.ensure_pg_db NAMEcreates 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 survivesframe services down.
Service credentials
The stack boots with intentional dev-only defaults — frame/devpassword on
postgres, minioadmin/minioadmin on minio — and both services bind to127.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 viastack_up(), or frame services up); unset, the defaults apply.
Two things to know:
- Postgres applies
FRAME_PG_PASSWORDonly when thepgdatavolume is
first created. Set overrides before your first boot; changing them later
leaves the existing cluster on its old password (reset withframe 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 fromensure_pg_db NAME [PASSWORD](defaultdevpassword) — pass your
own password there and put the same one inapp_env()'sDATABASE_URL.
License
Yorumlar (0)
Yorum birakmak icin giris yap.
Yorum birakSonuc bulunamadi