Skip to content
ArveSystadPublic

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

blackwall

A local, single-user, browser-based control room for coding agents. blackwall runs Claude Code, GitHub Copilot CLI and OpenCode as headless subprocesses against your own git repos. Tasks come from Jira Cloud issues, GitHub/GHE pull requests (Work on PR or Review PR), GitHub/GHE issues or Blackwall tasks you write yourself (free text).

Agents plan, grill, implement and review each other's work, on any of the CLIs. You approve the plan, answer the questions only you can answer, triage the findings and confirm every outbound action.

blackwall screenshot

Tasks can be picked up from Jira, Github Issues (or PRs for review), or the internal task-system in blackwall itself.

How to run: Quickstart

  1. Clone repo
  2. pnpm install
  3. pnpm start (or pnpm desktop to run as a desktop app (Elecetron app))

How it works

Inform ──► Plan review / grill ──► [human plan approval] ──► Implement ──► Checks ──► Code review panel
                                                              ▲                                 │
                                                              └──── blocking findings (≤3) ◄────┘
                                                                                                 │ approved
                                                                                                 ▼
                                                                              Summarize ──► [human finish confirm]
  • Review PR mode runs Inform → review panel → triage → inline PR review comments. At triage you can step through the PR's diff hunk by hunk from the Diff tab and comment on any hunk; your comments are posted with the reviewers' findings, inline as you wrote them. You can also delete findings you don't want posted before you post the review, or send an instruction from the chat to have the reviewers look at the whole PR again with it before anything is posted. The Context you give when creating the task reaches the reviewers. A PR stacked on another PR is reviewed, and its diff shown, against its own base branch, so each PR in a stack is reviewed on its own. Adding a PR that belongs to a stack also adds Review PR backlog items for the stack's other open PRs (skipping ones already tracked), labelled "stack #… · i/n" in the Backlog; the reviewers see the other PRs' changes as context but report findings only on their own PR. You can tick Approve to submit the review as an approval. It is ticked by default when there are no findings.
  • GitHub issue tasks work on a new feature/<n>-… branch and finish by pushing it, opening a PR that closes the issue and commenting on the issue. The PR body and comments carry a brief description of the change; the detailed summary stays in blackwall. You can also opt in to a comment on the issue when work starts and when you approve the plan; you see and edit each one first.
  • Each task gets its own git worktree at ../<repo>.worktrees/<task>.
  • The harness commits after each implement or fix round. Agents never push. A repo's default branch (set per repo in Settings → Repositories, default main) is pushed only when you click Push on its Backlog and confirm it; the pipeline never pushes it. New task branches fork from it, and before planning and implementing, while they have no commits of their own, they are fast-forwarded to the newest origin/<branch> (fetched first, falling back to the local branch). The pipeline never pushes or moves the default branch itself. Free-text tasks merge into it and PRs target it. With a GitHub remote, a Blackwall task can instead push its branch as feat/<slug> (or fix/<slug>) and open a pull request at finish.
  • Critical and High findings loop back to the implementer, for at most 3 fix rounds before escalating to you.
  • Reviewers are read-only. Implementers can edit and use the shell but cannot reach remotes.
  • The Security reviewer follows the OWASP Secure Agent Playbook. Blackwall ships a pinned copy and puts it in each task's .blackwall/playbooks/ before code review, so nothing needs installing on any CLI.
  • Claude Code, Copilot CLI and OpenCode agents can hand narrow jobs to a cheaper blackwall-worker sub-agent (Haiku on Claude Code, claude-haiku-5.5 on Copilot, and on OpenCode Haiku for anthropic/ and github-copilot/ models, otherwise the run's own model) that gets only a short brief. Implementers get one that can edit; planners and reviewers get a read-only one for fact-finding, such as locating code or reading a reference repo. The repo chat, voice commands and memory backfill get none. Running sub-agents show as small dots beside their task's dot on the home grid, and their work shows nested, collapsed, under the call that started them in Agent output.
  • A per-repo backlog with an auto-runner that respects concurrency caps and CLI usage limits. When the repo's local default branch has commits its origin counterpart doesn't (for example after free-text tasks merge into it), the Backlog header offers a confirmed "Push N commits to ". The Push button itself never fetches or forces; origin/<branch> is refreshed when tasks start new work. A repo can go Autonomous (after a confirmation): its backlog tasks then answer their own questions, approve their own plans and triage, merge into the local default branch and create their follow-ups, all locally; it never pushes or opens PRs.
  • A task can propose follow-up tasks, in its own repo or another registered one. You pick which to create at finish; they land in the backlog as waiting items. An analysis-only task can deliver just these follow-ups.
  • blackwall remembers lasting facts about each repo (conventions, pitfalls, decisions, commands) that tasks learn at Summarize, and gives the relevant ones to later tasks and chats in that repo. Notes from pull request tasks count only once the pull request is merged into the repo's main branch.
  • Interrupted steps resume the same CLI session, or start afresh with their original prompt if the CLI no longer has it.
  • After a task pushes its branch to GitHub or GHE, blackwall watches CI on the pushed commit and shows it on the task and its card: running, passed, the number of failed checks, timed out (after an hour), no CI, or unavailable. If CI fails, the task shows under Needs you with Fix CI. Fix CI runs a fix round with the failing checks' logs, then code review, and stops at Finish so you confirm the push again. The PR isn't opened twice, and squashing only touches commits that weren't pushed yet. Archive the task to dismiss a failure you fixed elsewhere. Reading CI needs Checks: read and Commit statuses: read (fine-grained) or repo (classic), and Actions: read for the job logs Fix CI uses; for an organisation with SAML SSO, authorise the token under Settings → Tokens → Configure SSO on GitHub. Without them the task shows a hint instead. Turn watching off per repo under Settings → Repositories → Watch CI after push.
  • Once a task has opened a pull request, Fetch comments and fix reads the reviewers' new comments on it and runs a fix round on them, then stops at Finish so you push again; comments already fixed are not picked up twice.
  • Once a Review PR task has posted its review, Refresh checks whether new commits landed on the pull request; if so, Re-review reviews only those commits and stops at triage so you can post a follow-up review.

Implementers may save files (screenshots, notes, logs, archives…) to .blackwall/artifacts/ in the worktree. They show in the task's Artifacts tab, updating while the task runs: images preview, text and code show as plain text (Markdown is rendered in the card), and other files download. The .blackwall/ scratch folder, also used for Jira attachments, is ignored by its own .gitignore and never committed.

Third-party content: the OWASP Secure Agent Playbook in packages/core/playbooks/owasp-secure-agent-playbook/ is licensed CC BY 4.0 by its authors; see its SOURCE.md.

Features

  • Agent library with role defaults per stage. Agents are not tied to a CLI: each repo picks the CLI its tasks run on, and a task can run single agents on the other one.
  • Finding tags and severities, with force-fix and force-ignore on any finding; force-fixing at the finish gate, or while the summary is being written, runs one more fix round right away
  • Step through the branch diff hunk by hunk from the Diff tab and comment on any hunk; the comments become force-fixed findings. Sending them at the finish or escalation gate runs a fix round right away; at triage they are fixed in the round that approving triage starts. In Review PR tasks, comments made at triage are added to the findings to post instead. A Review PR task can be stepped through while the reviewers still work: each hunk shows the reviewers' findings as they come in and the PR's existing GitHub review threads, refreshed every 20 seconds, and the reviewers are told about those comments so they don't repeat them
  • Connections to GitHub.com, GHE and Jira Cloud, with tokens in the OS keychain
  • Repo registry with auto-suggested check and setup commands; setup installs dependencies in each task worktree and re-runs only when lockfiles or commands change. Run commands per repo (e.g. pnpm dev) start from the Run project button in the top bar, which glows green while the project runs and shows its live output
  • Reference repos: pick other registered repos per repo (Settings → Repositories) that its planner, reviewers and chat may read, for work that spans repos. A new task or backlog item can pick its own; a task keeps the list it was created with, and its chat reads that list too. They are read-only, git doesn't work on them, and implementers never see them
  • Agent trust, per repo (Settings → Repositories): Locked (default) keeps agents in blackwall's sandbox; Trusted also loads the repo's own skills, sub-agents and instruction files, plus its MCP servers and hooks for implementers if you turn them on, while reviewers stay read-only; Unrestricted runs each CLI with everything allowed, so agents can push. Review PR tasks, and PR tasks with commits that aren't yours, always run Locked. Copilot under Trusted also loads your own ~/.copilot agents, skills and MCP servers. Each step shows the level it ran under.
  • Live agent output and per-round diffs, with how long each step took; a done task's header shows the time spent, excluding time spent waiting on you
  • Review requests: a pill on the home screen counts the open pull requests waiting on your review across every GitHub/GHE connection (requests to you or one of your teams, not drafts, not yet approved), and opens a list grouped by host at /reviews. Each PR has "Work on task", which adds it as a Review PR task to the backlog of the registered repo for its repository and starts it at once when that repo's backlog runs automatically; rows that already have a task or backlog item link to it instead. Private PRs only appear if the token has repo scope (classic) or read access to pull requests on those repos (fine-grained).
  • Assigned issues: a pill next to it counts the open issues assigned to you across every GitHub/GHE connection, and opens a list grouped by host at /issues. Each issue has "Work on task", which adds it with defaults to the backlog of the registered repo for its repository and starts it at once when that repo's backlog runs automatically; rows that already have a task or backlog item link to it instead. Private issues only appear if the token has repo scope (classic) or Issues read access on those repos (fine-grained).
  • Repo issues: each repo's Backlog lists the repository's open GitHub issues under "GitHub issues", whoever they are assigned to, up to the 100 most recently updated. "Start working" assigns the issue to you and starts a task right away, even when the runner is off; assigning needs repo scope (classic) or Issues write access (fine-grained). Private repos need the same token scopes as Assigned issues. The GitHub issue lists (here and in Assigned issues) refresh every 60 seconds by default while the window is focused; change it under Settings → Backlog. With "Include remote issues" (under "Run this repo's backlog"), the runner takes the top open GitHub issue that is unassigned or assigned to you, or, when there is none, the top such issue of the repo's Jira project, whenever the repo's queue has nothing left to start, adds it to the Queue and starts it, one issue at a time; it never assigns, transitions or comments on either. Pause an imported item to skip its issue (a deleted one comes back).
  • Memory, per repo (Settings → Repositories): review the notes blackwall saved about the repo when tasks finished, and add, edit, pin or delete them. Pinned notes always reach agents, and a note you edit or pin is never replaced by a later summary. Notes from pull request tasks wait under "Waiting for merge" until the PR merges. "Learn from past tasks" runs the summarizer once on each finished task that has no notes yet, to fill the vault from work done before it existed.
  • Jira issues: set a Jira project key (such as ABC) on a repo in Settings → Repositories, and its Backlog lists that project's open issues (any status outside Jira's Done category) that are unassigned or assigned to you under "Jira issues", up to the 100 most recently updated. "Start working" starts a task right away, even when the runner is off; it never assigns or transitions the issue. Only Jira connections with a saved token count: with one, its site is used; with several, the list shows an error instead of issues. The list refreshes at the same interval as the GitHub issue lists (Settings → Backlog).
  • Chat: a panel on the right (C, or the chat button in the top bar) for the repo picked in the top bar, on every page, task pages included. Ask about its code, backlog and tasks; the agent runs read-only in the repo's checkout on the repo's default CLI. Replies stream in as the agent writes them (Claude and Copilot). Each task's page also has its own chat, the task channel under the task's header (M), kept apart from the repo chat: it gets the task's error, plan and open questions, so you can ask why it failed. Its history folds away, and the page remembers whether it is open. /clear there clears only that task's chat, and deleting a task deletes its chat. It can propose actions: a new backlog task, instructions to a task waiting at a gate, an answer to one of a task's open questions, stopping a task, or resuming one, optionally with guidance for the agent steps that failed or stopped. Each shows as a card naming the task, and nothing happens until you click Apply; applied cards stay Done. "Turn into task" under any reply adds a new backlog task card for it, titled with its first line. /clear or Clear starts over, and asks first while an answer is running. The conversation is saved per repo, so it survives a restart, including which cards were applied; /clear or Clear deletes it. In the task channel, on a task waiting at a gate that takes a message, or a failed or interrupted one, a second button next to Send (Ctrl+Shift+Enter / ⌘⇧↵) sends what you typed straight to the task without asking the agent: to the gate (for example "Request changes · planner"), or as guidance when it resumes ("Retry with this")
  • Voice control: hold the mic in the top bar (or focus it and hold Space) and speak a command for the repo picked there: "create a new task to add a dark mode toggle", "add a description: it should remember the choice", "confirm", "start the dark mode task", "turn run backlog on". Commands act at once: "create a task" opens the New task form filled in, later commands update it, and "confirm" creates it, once, even with several windows open. Speech is transcribed on your machine with sherpa-onnx; only the transcript goes to the repo's default CLI, which carries it out. Settings → Voice picks the model (the default English one, about 100 MB, or the multilingual Whisper small) and downloads it into ~/.blackwall/models with its Download button; pnpm voice:model [id] does the same from the terminal, building the workspace first if needed. Settings → Voice also sets a hold-to-talk key you can hold anywhere in blackwall except text fields; in the desktop app it works system-wide, even with another app in front (macOS asks once for the Accessibility permission). An F-key is best, since the key also reaches the app in front; browser and app shortcuts such as Ctrl+W or ⌘S are refused
  • Search: Ctrl+K / ⌘K or the search icon in the top bar finds tasks (archived included), backlog items and repos; current repo first, or limit to it
  • Needs-you inbox, with the count in the tab title (and on the dock or taskbar badge in the desktop app) and optional desktop notifications (Settings → Notifications)
  • Export and import (Settings → Data): Export downloads one zip with your settings, connections, repositories, agents, tags, backlog, tasks and memories, with or without agent transcripts. No tokens are exported, and repo checkouts and worktrees are not included. Import merges an export into the data in place after backing up the current database to ~/.blackwall/backups/: new rows are added, while existing rows and settings are kept. Repositories are matched by git remote, or by folder when there is no remote; when the remote matches but the folder differs, or the folder matches but the remote differs, you choose to merge the repository into the local one or skip it. Import is refused while tasks run, are queued or are finishing. Afterwards it reports what was imported and skipped, and lists connections that need a token, repositories whose folder is missing, and how many task worktrees are missing
  • Optional desktop window with a tray icon (pnpm desktop)
  • Dark and light themes
  • Keyboard shortcuts: Ctrl+K / ⌘K search, N new task, C chat, M message the open task, T theme, / filter the inbox, Esc to close or go back

Requirements

Running

git clone <this repo> ~/code/blackwall
cd ~/code/blackwall
pnpm install
pnpm start          # builds if output is missing or stale, starts on 127.0.0.1 and opens your browser

pnpm start -- --no-open skips opening the browser. pnpm start -- --port 4711 picks a port (default 4711, or BLACKWALL_PORT). The build is skipped when nothing under the workspace sources or config has changed since the last pnpm start build.

The server binds to 127.0.0.1 only and prints a URL containing a per-launch token. Data lives in ~/.blackwall/; BLACKWALL_HOME overrides the data directory. Personal access tokens are stored in your OS keychain, never in the database.

For headless use, set BLACKWALL_TOKEN_<CONNECTION> to override a connection's keychain token. The suffix is the connection name in upper case with other characters replaced by _, so acme.ghe.com reads BLACKWALL_TOKEN_ACME_GHE_COM.

Desktop app

pnpm desktop            # builds if output is missing or stale, then opens blackwall in its own window
pnpm desktop:shortcut   # Windows: adds a Start Menu shortcut you can pin to the taskbar

The desktop app is an Electron window around the same server that draws its own title bar that follows the theme, run from a source checkout after pnpm install. There are no installers yet.

  • Requirements: everything browser mode needs. Node.js 22+ must be on PATH, because the server runs on your system Node, not Electron's. On macOS and Linux the app reads PATH from your login shell, so CLIs installed by a version manager are found even when launched from Finder or a desktop launcher.
  • Port: 4712 (BLACKWALL_DESKTOP_PORT overrides it). The port stays fixed so the theme and selected repo are kept between launches. BLACKWALL_PORT and BLACKWALL_WEB_PORT are ignored in desktop mode.
  • Data: the same data directory as browser mode (~/.blackwall/, or BLACKWALL_HOME). Only one instance can use a data directory at a time, so pnpm desktop refuses to start while pnpm start is running on the same one, and the other way round.
  • Taskbar shortcut (Windows): pnpm desktop:shortcut adds blackwall to the Start Menu with its icon. Right-click it there and pick Pin to taskbar. Launching from it rebuilds first when the sources have changed, just like pnpm desktop, and shows a small "Building" window while it does. If blackwall is already running it brings that window forward instead.
  • Tray and badge: the tray icon opens the window and holds Quit. The number of tasks that need you shows on the dock or taskbar icon and in the tray tooltip.
  • Quitting: closing the window, Quit in the tray or the app menu all ask before quitting, and say how many agents are running. Confirming stops those agents the same way Ctrl+C does for pnpm start, so their steps resume on the next launch.

Quick-launch function

Add a one-word launcher to your shell profile so blackwall starts the tool from anywhere.

Windows (PowerShell)

Open your profile with notepad $PROFILE and add:

function blackwall {
    pnpm --dir "C:\Code\blackwall" start -- @args
}

macOS / Linux (bash or zsh)

Add to ~/.bashrc or ~/.zshrc:

blackwall() {
  pnpm --dir "$HOME/code/blackwall" start -- "$@"
}

Replace the path with where you cloned the repo. Restart the shell (or . $PROFILE / source ~/.zshrc), then run blackwall from any directory. Flags pass through: blackwall --no-open --port 5000.

Development

pnpm dev runs the server under tsx watch plus the Vite dev server with hot reload. On Windows, ./start.ps1 does the same and opens the browser once Vite is up.

pnpm test           # Vitest, against sources (no build needed)
pnpm typecheck
pnpm lint
pnpm format:check

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages