Factory Floor

What is Factory Floor?

Factory Floor is a native macOS development workspace for running multiple, parallel “workstreams” in one place. It coordinates git worktrees (branches and isolated directories), Claude Code sessions, development terminals, and dev-server browsing—so you can switch tasks without losing local state.

The app is designed around isolation: each workstream gets its own branch, terminal, and AI agent session running concurrently. It uses Ghostty’s GPU-rendered terminal and supports setup/run/teardown automation via a per-project configuration file.

Key Features

• Single-window workspace for projects and workstreams: view terminals, AI sessions, and an embedded browser together instead of juggling separate apps.
• Git Worktrees per workstream: each workstream uses its own branch and worktree, and the app supports task switching without stashing; .env files are automatically symlinked.
• Claude Code integration with session persistence: Claude Code sessions keep a persistent context and can be resumed across app restarts using automatic session IDs.
• Tmux-based persistence for agent sessions: agent sessions survive app restarts via tmux on a dedicated socket to reduce interrupted workflows.
• Embedded browser with auto-port detection: the embedded browser detects the port your run script starts listening on and navigates to it automatically.
• Project lifecycle scripts via .factoryfloor.json: configure setup, run, and teardown scripts per project; scripts run in the workstream directory using your login shell, with all fields optional.
• Environment variables available in every terminal and script: terminals and scripts receive variables such as project/workstream names, paths, and a deterministic FF_PORT.
• GitHub integration via gh CLI: the project view can show repo info, open PRs, and branch PR status (powered by the gh CLI).
• Keyboard-first navigation and shortcuts: shortcuts are available for creating projects/workstreams, switching tabs/workspaces/projects, archiving workstreams, and opening editors/terminals (including external options).

How to Use Factory Floor

1. Install Factory Floor: install it via brew install --cask alltuner/tap/factoryfloor or by downloading the source.
2. Add a project: drop a directory into the sidebar or create a new one; Factory Floor detects git repos, installed tools, and GitHub connections automatically.
3. Create a workstream: create a workstream to generate a new git worktree and branch, start a Claude Code session, open a terminal, and add a browser tab.
4. Run your dev server and preview: configure setup, run, and (optionally) teardown in a .factoryfloor.json at the project root; when the run command starts listening, the embedded browser opens the detected port.
5. Switch tasks without losing context: move between workstreams; the tmux-based persistence and Claude Code session IDs are used to keep context across app restarts.

Use Cases

• Parallel feature work in one repo: create separate workstreams for different tasks so each has its own branch, terminal, Claude Code session, and browser tab while you switch between them.
• Task-scoped dependency setup: define a project setup script such as npm install so dependencies are installed when a worktree/workstream is created.
• Consistent dev-server runs with deterministic ports: use the FF_PORT environment variable in your run script (for example, PORT=$FF_PORT npm run dev) so each workstream uses its own predictable port.
• Automatic cleanup when archiving: set a teardown script (for example, docker-compose down) to stop containers or clean resources when a workstream is archived.
• Resume AI-assisted debugging across sessions: rely on persisted Claude Code session IDs and tmux socket persistence to continue work after restarting the app.

FAQ

• Is Factory Floor open source? Yes. Factory Floor is MIT-licensed and the source code is available on GitHub.

• How does the app open my dev server in the embedded browser? When you start the project via a workstream run script, Factory Floor uses auto-port detection to determine which port the run command is listening on and navigates the embedded browser to that address.

• Where do I configure setup/run/teardown automation? Add a .factoryfloor.json file in your project root. It can include setup, run, and teardown script commands; all fields are optional.

• What environment variables are available to scripts and terminals? Every workstream terminal and any setup/run/teardown script can use environment variables such as FF_PROJECT, FF_WORKSTREAM, FF_PROJECT_DIR, FF_WORKTREE_DIR, and FF_PORT.

• Does Factory Floor require GitHub tooling for its GitHub view? The GitHub integration in the project view is powered by the gh CLI.

Alternatives

• Local terminal + tmux + manual git worktree workflow: you can approximate the same underlying approach (worktrees, tmux persistence, and dev-server monitoring) using separate tools, but you won’t get the single-window orchestration and embedded browser behavior.
• IDE-integrated multi-root workspaces: IDEs can manage multiple projects and terminals, but they may not provide explicit git worktree isolation per task with the same script-driven lifecycle and port-detection flow.
• Git branch-per-task with stashing: a simpler git approach can support context switching, but it typically relies on stashing/cleanup rather than isolated worktrees and task-scoped environments.