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.1 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,
the upstream lists of non-Markdown files, and the prompts of generated
images and videos.
- Images and videos from your own providers. A generated image or video
is an ordinary file in the folder, and that file is its card. The images,
videos, audio, and notes connected to a card are its inputs, in order, and
its prompt and settings travel with the file. BaseHalf runs the image and
video models of 13 providers with the user's own keys.
- 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"]
mirror --> generation["generation.yaml / made.yaml"]
The format is deliberately plain:
- A Markdown note lists the files that flow into it under the
upstream key of
its frontmatter.
.bh/mirror/<path>/upstream.yaml keeps the upstream list of a folder, PDF,
image, video, or other non-Markdown file.- A generated image or video is an ordinary file under the name of its card.
.bh/mirror/<path>/generation.yaml holds the prompt, model, and settings
of its next generation, and .bh/mirror/<path>/made.yaml the record of the
generation that made it. A generation.yaml whose file does not exist yet
is a draft: a card on the canvas that has not generated.
.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: the records of generations that run
on this computer, 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, non-Markdown upstream lists, and the
prompts, drafts, and records of generated files 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 images and videos on cards with your own key for ByteDance
(Seedance), Kling, Alibaba (Wan), MiniMax (Hailuo), Vidu, Google, PixVerse,
Luma, Runway, xAI (Grok Imagine), LTX, Black Forest Labs, or OpenAI (images).
A new image or video card is a draft until it generates; its file then
lands in the folder under the card's name. 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 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
image and video cards.
Install
- Download
BaseHalf-0.6.1-darwin-arm64.dmg from
the latest release.
- Open the DMG and drag
BaseHalf.app into Applications.
- 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, Sequence, references, navigation,
workspace
src/vs/platform/basehalfProviders/ the image and video provider modules and
the model catalog, in the shared process
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
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
- VS Code substrate, BaseHalf product. Prefer VS Code services and
workbench patterns for infrastructure; keep BaseHalf's product layer
canvas-first.
- Module-complete migration. Port modules to product quality rather than
landing placeholder UI or disconnected demo paths.
- Files/Git/Search on the left. Reuse VS Code mechanics, but route
activation into BaseHalf folder canvases and card detail.
- Agent Area owns the right. Terminal APIs and extension-created terminals
render as Agent Area sessions, not the stock terminal panel.
- Fixed shell, one main canvas. AI Video is BaseHalf's own code: it adds
templates, card projections, the Sequence view, and the requests that
image and video cards send to their providers without replacing the
canvas model, BaseHalf navigation, the sidebar, or Agent Area. There is no
plugin platform: nothing can be installed or published for BaseHalf. See
built-in AI Video and no plugins.
- Markdown shares one truth. Rich, source, and preview projections operate
over the same Markdown working copy.
- 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:
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.
- Read CONTRIBUTING.md for build/test commands and architecture
invariants.
- Open a PR; CI runs the project checks.
- 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.
