Half AI. Half human. Half machine. Half flesh.
A canvas-first desktop workspace for thinking with files and agents.

BaseHalf is an open-source, local-first desktop workspace built on a real VS Code substrate. It keeps your files in a normal folder, gives humans a canvas/card-detail way to navigate that folder, and records how the materials connect in the files themselves so agents can stay oriented in the same materials.

Status: BaseHalf 0.6.0 is the current public macOS Apple Silicon release. It is usable, early, and changing quickly. The product has moved from the old hand-rolled Electron/core shell onto vscode-base/, where VS Code provides the application substrate and BaseHalf owns the canvas-first product layer.

Download the latest build from GitHub Releases. The current macOS build is unsigned and unnotarized, so Gatekeeper may block the first launch. After dragging the app to Applications, run:

xattr -dr com.apple.quarantine /Applications/BaseHalf.app

Why BaseHalf

AI agents are good at reading and editing files, but people think through spatial context, references, partial attention, and "where was I?" signals. BaseHalf is the meeting place: a real folder remains the source of truth, while the app adds a visual canvas, file cards, Markdown projections, Git/Search/File surfaces, and agent-readable connections beside the work.

BaseHalf is not trying to become the agent. It is a substrate for compound work: humans keep the map, agents use their own tools, and both sides can inspect the same local project without a cloud account or hidden database.

The workspace map is a core part of that product direction, not a legacy detail. Each note lists what flows into it in an upstream list that agents read along with the note, and .bh/ holds BaseHalf project metadata such as canvas layout, descriptions, and reading aids. BaseHalf also records what you last selected (a folder, cards, or text in a note), so that an agent knows what you mean by "this".

Product Shape

• Canvas first. Folders open as canvases. Files open as full-screen card detail inside the BaseHalf flow. VS Code editor tabs remain fallback plumbing, not the default product model.
• Real files stay real. Markdown, code, media, and project files remain in the workspace folder. Git, external editors, and agents see ordinary files.
• Connections live in the files. BaseHalf keeps user content in real files. A note's upstream frontmatter lists what flows into it, and .bh/ holds BaseHalf project metadata: canvas layout, descriptions, reading aids, and the upstream lists of non-Markdown files.
• Video from your own providers. A Video node is a prompt over its connections: the images, videos, audio, and notes connected to it are its inputs, in order. It runs 51 models from 12 video providers with the user's own keys, and the video it makes is an ordinary file in the workspace.
• VS Code is the lower layer. BaseHalf reuses VS Code's Explorer, Search, SCM/Git, quick input, working-copy/file services, menus, settings, extension host, and terminal process APIs.
• The left sidebar is small. The visible sidebar product surface is Files, Git, and Search. Open Editors, generic Extensions, Debug, Testing, Problems, Remote Explorer, stock Chat/Copilot/Sessions, and the stock terminal panel are hidden or remapped while BaseHalf keeps its own product shape.
• The right side is Agent Area. Agent Area hosts TUI agents, curated extension agents, and plain shell sessions with tabs, panes, splits, restart, kill, resize, and zoom controls.
• Markdown has projections. A Markdown file is one working copy with three card-detail projections: rich by default, source for raw Markdown, and preview for read-only rendered Markdown.

Agent Area

BaseHalf's first-class session choices are intentionally narrow:

• Codex - runs the codex CLI as a TUI session.
• Claude Code - runs the claude CLI as a TUI session.
• Codex Extension - hosts the curated VS Code Codex extension experience.
• Claude Code Extension - hosts the curated VS Code Claude Code extension experience.
• Terminal - opens a shell for OpenCode, Gemini CLI, or another terminal based agent.

Extension support starts curated, not marketplace-open. BaseHalf currently allows only the extension families needed for Git/GitHub auth and the Codex / Claude agent surfaces.

BaseHalf offers to install a basehalf skill for Claude Code, Codex, and other agents that load skills. It tells them where a card's description and connections are, what moving a file does to them, and what the user last selected. BaseHalf asks first and adds the skill to the agents' own settings, not to your folder.

Local Workspace Protocol

BaseHalf publishes context in files and never injects workspace content into prompts. Agents read the workspace files directly, including each note's upstream list, and learn where the rest is under .bh/ from the basehalf skill. Claude Code TUI sessions started from Agent Area also receive a short, static BaseHalf instruction at launch. BaseHalf no longer adds instructions to CLAUDE.md or AGENTS.md. This protocol is the shared language between the app, the human's visual workspace, and file-based agents:

flowchart LR
  human["Human"] --> app["BaseHalf"]
  app --> substrate["VS Code substrate"]
  app --> files["Workspace files"]
  app --> mirror[".bh/mirror"]

  agent["Agent"] --> area["Agent Area"]
  area --> files
  area --> mirror

  files --> upstream["upstream lists"]
  mirror --> badge["badge.yaml"]
  mirror --> canvas["canvas.yaml"]
  mirror --> aids["adhd.yaml / appearance.yaml"]
  mirror --> sidecar["upstream.yaml"]

Loading

The format is deliberately plain:

• A Markdown note lists the files that flow into it under the upstream key of its frontmatter; a .bhnode keeps the same list in its upstream field.
• A Video node is a .bhnode that also holds its prompt, provider, model, and settings. The videos it makes are written under outputs/.
• .bh/mirror/<path>/upstream.yaml keeps the upstream list of a folder, PDF, or other non-Markdown file.
• .bh/mirror/<path>/badge.yaml stores a file or folder description.
• .bh/mirror/<folder>/canvas.yaml stores the place and size of every card and edge anchors for that folder canvas.
• .bh/mirror/<file>/adhd.yaml stores per-file reading aids such as highlights and read ranges, and .bh/mirror/<path>/appearance.yaml stores visual presentation.
• .bh/cache/ holds machine-local state: run leases, undo stashes, recovery copies of files BaseHalf could not read, and selection.yaml, what the user last selected, for agents to read.

BaseHalf never edits your .gitignore. It writes one ignore file of its own, .bh/.gitignore, which keeps card places (canvas.yaml) and .bh/cache/ out of git. Descriptions, reading aids, and non-Markdown upstream lists can be committed and travel with the folder. Canvas viewports are kept per machine, outside the workspace.

References are an explicit directed context-flow graph: A → B means A's context flows into B. The graph is not a tree; many-to-many relationships and cycles are valid, while self-references are not. Each reference is stored once, in B's upstream list; BaseHalf derives the reverse direction ("downstream") and never stores it. Users and Agents create cards and references explicitly, and may edit upstream lists as ordinary text. An entry that names a missing file stays visible as a broken entry until someone relinks or removes it. Markdown links remain ordinary document navigation and never create a BaseHalf reference automatically. Canvas edges visualize the same graph without relationship labels or notes.

User files remain content truth. Automated BaseHalf services observe files and never modify them in the background; BaseHalf changes an upstream list only through an operation the user starts or confirms, or when an agent in the Agent Area moves a file through BaseHalf. Agents edit files with their own tools. Claude Code sessions that receive BaseHalf's launch context (local macOS and Linux Agent Area sessions) move files through BaseHalf, so descriptions, layout, and references follow.

What Works Today

• Open a real local folder and land in the BaseHalf canvas workbench.
• Browse Files, Git, and Search using VS Code-backed side views.
• Open folders as canvases and files as BaseHalf card detail instead of editor tabs.
• Drag cards, persist positions, explicitly connect directed context-flow references with anchored edges, and use snap guides.
• Select several cards with a marquee, move them as one set, arrange them in a grid, a row, or a column, and tidy a whole canvas along its connections, then keep or revert the result.
• Rename a card in place by double-clicking its name. Notes are named without .md.
• Read notes rendered on their cards, with tables, images, and task boxes, and edit a note of up to 128 KiB on its card.
• Use Quick Open and Quick Text Search while result activation still routes back into BaseHalf card detail.
• Edit Markdown in rich mode, switch to source or preview, and keep Markdown as the single file truth.
• Open code and non-Markdown text through the source card detail.
• Use VS Code's native Git provider, repository state, branch quick pick, SCM refresh, and publish-branch flow.
• Run Codex, Claude Code, curated extension agents, and shell agents inside the Agent Area. Agents can read what you selected: a folder, one or several cards, or text in a note. The status bar shows what they see.
• Generate videos from Video nodes with your own key for ByteDance (Seedance), Kling, Alibaba (Wan), MiniMax (Hailuo), Vidu, Google, PixVerse, Luma, Runway, xAI (Grok Imagine), LTX, or Black Forest Labs. The panel shows each model's own settings, and a running generation continues after a restart. What a generation costs is in your provider's console.
• Find BaseHalf's settings, the Video Providers page, and About (the version and updates) in Settings under BaseHalf.
• Update in place: an update is downloaded once, in the background, and installed when BaseHalf quits, or at the latest at its next start. Release Notes opens the release page.

The smoke guards this shape in five suites: the workbench (hidden competing surfaces, the Files / Git / Search sidebar, Agent Area sessions, Source Control, and Settings), the canvas, Card Detail with its Markdown projections, navigation (Quick Open, Quick Text Search, and Explorer routing), and the Video node.

Install

1. Download BaseHalf-0.6.0-darwin-arm64.dmg from the latest release.
2. Open the DMG and drag BaseHalf.app into Applications.
3. If macOS blocks first launch, remove the quarantine attribute:

xattr -dr com.apple.quarantine /Applications/BaseHalf.app

The app's update feed is served from GitHub Releases through the signed BaseHalf update manifest.

Develop From Source

Current desktop development happens in vscode-base/. The older packages/ tree is useful for migration history and tests, but new desktop-facing product work should be VS Code-aligned workbench/platform code.

Requirements:

• macOS for the current desktop packaging path.
• Node 24.17.0 from vscode-base/.nvmrc.
• npm.

cd vscode-base
nvm use
npm install
npm run compile
./scripts/code.sh

Useful checks:

cd vscode-base
npm run typecheck-client
./scripts/test.sh
npm run basehalf:smoke

For BaseHalf UI/routing changes, npm run basehalf:smoke is the important product smoke. If out/ is already current, npm run basehalf:smoke-no-compile skips the compile step. Its steps are in suites by area, each on a BaseHalf of its own, and -- --suite canvas runs one of them (vscode-base/scripts/basehalf-smoke/README.md).

Package a macOS release build:

cd vscode-base
build/basehalf/package-darwin.sh arm64

Repo Layout

vscode-base/                         current desktop product source
  src/vs/workbench/basehalf/         BaseHalf's workbench code, a folder per
                                     feature: canvas, card detail, Agent Area,
                                     video, references, navigation, workspace
  src/vs/platform/update/            BaseHalf's update service and protocol,
                                     beside VS Code's (basehalf*.ts)
  extensions/basehalf/               rich Markdown editor, in-card note
                                     editor, and other bundles
  extensions/basehalf-ai-video/      built-in AI Video: Sequence, the starter
                                     template, and the video provider modules
  build/basehalf/                    macOS package, DMG, and update scripts
  BASEHALF_UPSTREAM.md               VS Code import baseline

docs/                                public specs, decisions, and policies
  harness/                           BaseHalf's progressive development harness
private-docs/                        private product/architecture decision corpus
packages/                            historical BaseHalf core/desktop material

Architecture Principles

1. VS Code substrate, BaseHalf product. Prefer VS Code services and workbench patterns for infrastructure; keep BaseHalf's product layer canvas-first.
2. Module-complete migration. Port modules to product quality rather than landing placeholder UI or disconnected demo paths.
3. Files/Git/Search on the left. Reuse VS Code mechanics, but route activation into BaseHalf folder canvases and card detail.
4. Agent Area owns the right. Terminal APIs and extension-created terminals render as Agent Area sessions, not the stock terminal panel.
5. Fixed shell, extensible main canvas. The built-in AI Video adds templates, card projections, the Sequence view, and the requests of the Video node to its providers without replacing the canvas model, BaseHalf navigation, the sidebar, or Agent Area. The plugin platform it is built on is frozen: nothing can be installed or published. See built-in AI Video and the frozen plugin platform and the plugin architecture.
6. Markdown shares one truth. Rich, source, and preview projections operate over the same Markdown working copy.
7. BaseHalf does not secretly edit user files. Automated services never write user files in the background, and BaseHalf writes no agent guides or focus files into the workspace. Explicit or confirmed user actions, or external agents, make content and upstream changes.

Designed For

• Curious learners using AI: build understanding through a canvas of source material, notes, references, and active agent sessions.
• Agent-assisted project work: keep files, Git state, search results, and agent terminals in one local workspace.
• Research maps: arrange folders and files spatially, connect supporting materials, and return to each canvas where you left it.
• Local-first project memory: keep lightweight descriptions, references, canvas positions, and reading state beside the project itself.

Community

Community links are intentionally lightweight while BaseHalf is early:

• GitHub Discussions - questions, ideas, and build-in-public updates.
• Twitter / X - short public progress notes.
• Discord - async community chat.
• QQ Users - Chinese user community.
• QQ Developers - Chinese developer community.

If you are trying BaseHalf with Codex, Claude Code, OpenCode, Gemini CLI, or another local-file agent, we would love to hear what you build.

Contributing

BaseHalf is early and deliberately narrow. Please open an issue or discussion before sending a non-trivial external PR so we can align on scope first.

1. Read CONTRIBUTING.md for build/test commands and architecture invariants.
2. Open a PR; CI runs the project checks.
3. Sign the CLA when prompted. Contributions must use permissively-licensed dependencies.

Maintainers push main directly after local lint, typecheck, tests, and an in-session adversarial review.

Bug reports, ideas, and discussion are always welcome. By participating you agree to our Code of Conduct.

License

BaseHalf is Apache-2.0. VS Code-derived portions in vscode-base/ retain their upstream MIT license and third-party notices.

Contributions require a signed CLA. The "BaseHalf" name and logo are trademarks of Pointa Labs, Inc. See the trademark policy.