<div align="center">
  <img src="./src-tauri/icons/128x128.png" width="96" height="96" alt="Workwall icon">
  <h1>Workwall</h1>
  <p><strong>A local-first visual wall for turning ideas into shipped work.</strong></p>
  <p>Handwritten sticky notes, flexible swimlanes, an AI card partner, and a loopback automation API—inside one tactile desktop workspace.</p>
  <p>
    <a href="./README.md"><strong>English</strong></a>
    ·
    <a href="./README.zh-CN.md">简体中文</a>
  </p>
  <p>
    <img src="https://img.shields.io/badge/version-0.1.3-dcf739?style=flat-square" alt="Version 0.1.3">
    <img src="https://img.shields.io/badge/platform-Windows-2979ff?style=flat-square&logo=windows11&logoColor=white" alt="Windows">
    <img src="https://img.shields.io/badge/data-local--first-0c4a3e?style=flat-square" alt="Local-first">
    <a href="./LICENSE"><img src="https://img.shields.io/badge/license-GPL--3.0-f2a65a?style=flat-square" alt="GPL-3.0 license"></a>
  </p>
  <p>
    <a href="https://github.com/micky-meecky/WorkWall/releases/latest"><strong>Download for Windows</strong></a>
    ·
    <a href="#run-from-source">Run from source</a>
    ·
    <a href="./docs/MCP.md">Connect an AI agent</a>
  </p>
</div>

![A Workwall board filled with software delivery tasks](./docs/images/workwall-board-overview.png)

## A wall you can think on

Workwall brings the freedom of a physical planning wall to a local desktop app. Arrange work across editable stages and task-type swimlanes, move and resize notes naturally, and keep the whole project visible without turning it into another rigid issue tracker.

| Plan visually | Work with AI | Keep control | Automate safely |
| --- | --- | --- | --- |
| Shape projects with editable stages, swimlanes, colours, card sizes, rotations, and layouts. | Discuss a card over multiple turns, review a concrete proposal, then choose whether it may update the note. | Boards live on your machine. Deleted projects move to a recoverable local trash folder. | A loopback-only HTTP API and typed MCP tools let trusted coding agents work with an explicitly selected board. |

## Highlights

- **Tactile Kanban wall** — layered 2D paper, natural curls and shadows, handwritten fonts, flexible stage widths, and adjustable swimlane heights.
- **Independent projects** — create, rename, colour, duplicate, archive, restore, or recoverably delete workspaces without mixing their board data.
- **AI card partner** — stream replies into a real conversation, optionally inspect provider reasoning while it is running, and preserve the visible discussion with each card.
- **Review before write** — the assistant can propose a task, next action, notes, category, and stage, but it changes the card only after explicit approval.
- **Local-first persistence** — atomic workspace files, browser-cache fallback, per-project undo history, and no required Workwall cloud account.
- **Multilingual workspace** — switch the interface among nine languages and keep translated card copies without overwriting the original text.
- **Agent-ready automation** — inspect and update projects, cards, categories, stages, and layout through the local API or MCP adapter.

## AI collaboration that stays conversational

![Workwall sticky-note editor with the AI card assistant](./docs/images/workwall-ai-assistant.png)

The card assistant is designed for discussion, not one-shot generation. Ask questions, refine intent, and request a structured fill proposal when the card is ready. The proposal remains separate until you approve it; rejecting it returns you to the conversation for another iteration.

Visible replies stream as they arrive. When a compatible provider supplies reasoning increments, the current reasoning panel can be expanded or collapsed and closes automatically after completion. Workwall retains up to 40 visible user and assistant messages per card, while provider keys and reasoning text never enter board files.

## Download

Download the newest Windows installer from [GitHub Releases](https://github.com/micky-meecky/WorkWall/releases/latest). The packaged desktop app includes its Python sidecar, so end users do not need to install Python separately.

> Workwall is currently an early desktop release for Windows x64. Keep a backup of important workspace files before testing a new release.

Windows normally provides the required WebView2 runtime. If the app cannot create its window, install the current [Microsoft Edge WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2/).

## Run from source

The local web service uses the Python standard library. Python 3.11 or newer is recommended.

```powershell
./manage-workwall.ps1 -Action Start -NoPause
```

Open [http://127.0.0.1:4177/](http://127.0.0.1:4177/) and check readiness at [http://127.0.0.1:4177/api/health](http://127.0.0.1:4177/api/health). On Windows, you can also double-click `manage-workwall.cmd` for the start, stop, restart, and status menu.

For the native desktop development shell:

```powershell
npm install
npm run desktop:dev
```

Create a Windows installer with:

```powershell
npm run desktop:build
```

## Board controls

| Gesture | Result |
| --- | --- |
| Middle-button drag anywhere on the board | Pan the workspace, even over cards and dividers |
| Drag a sticky note | Move it within its current task-type swimlane |
| `Alt` + drag a sticky note | Move it to another task-type swimlane |
| `Alt` + mouse wheel | Zoom the board from 100% to 180% |
| `Shift` + wheel over a note | Resize that note |
| `Shift` + wheel away from notes | Resize all notes while preserving their relative sizes |
| Mouse wheel over a note | Fine-tune its rotation |
| `C` | Open the new-card composer when no dialog or text field is active |
| `Ctrl/Cmd + Z`, `Ctrl + Y`, or `Ctrl/Cmd + Shift + Z` | Undo or redo recent board changes |

## Local-first by design

Workspace data stays outside the Git repository:

- Windows: `%LOCALAPPDATA%\Workwall\state\<workspace-id>.json`
- Other platforms: `~/.workwall/state/<workspace-id>.json`

Replacing or updating the application does not intentionally replace these board files. Project deletion moves the selected JSON file into a timestamped `trash` directory rather than erasing it immediately.

AI provider metadata is stored separately. On Windows, API keys are encrypted for the current user with DPAPI and are never returned by the API or written to board state, exports, MCP payloads, or logs. AI features contact only the public HTTPS provider configured by the user; the board itself remains usable without a provider or network connection.

## MCP and local API

Install the MCP adapter dependency:

```powershell
python -m pip install -r requirements-mcp.txt
```

The repository includes `.codex/config.toml`, which registers `mcp_server.py` against the running loopback service. Restart Codex or open a new task from this repository after changing MCP configuration.

Every MCP board operation requires an explicit `workspace_id`; there is no implicit current board. The adapter does not read workspace files directly and never exposes arbitrary HTTP requests or provider keys.

- [MCP tools and safety boundaries](./docs/MCP.md)
- [Loopback API reference](./docs/API.md)

## Architecture

```text
Tauri / WebView2 desktop UI ──┐
Browser UI ──────────────────┼──> Python loopback service ──> local workspace JSON
Trusted coding agent ─> MCP ─┘                └─────────────> configured AI provider (optional)
```

Production sticky-note rendering remains Canvas/2D based. Three.js and GLB experiments are isolated in the sticky-shape research lab and are not loaded by the main board.

## Validation

```powershell
python -m unittest discover -s tests -v
python scripts/validate_sticky_assets.py
```

After layout or rendering changes, also verify the board at desktop size and exercise card editing, panning, zooming, lane changes, and restart persistence.

## Documentation

| Document | Contents |
| --- | --- |
| [Product behaviour](./docs/features/FEATURE_WORKWALL.md) | Current user-visible behaviour and acceptance checks |
| [API reference](./docs/API.md) | Local HTTP routes and AI streaming events |
| [MCP guide](./docs/MCP.md) | Tool contracts, setup, and safety boundaries |
| [Local operations](./docs/operations/LOCAL_OPERATIONS.md) | Service management, storage, recovery, and packaging |
| [Changelog](./CHANGELOG.md) | Notable changes by release cycle |

## Project status

Workwall 0.1.3 includes the multi-project local board, Tauri desktop shell, packaged Python loopback sidecar, Windows installer, persistent AI provider settings, encrypted API keys, streaming card conversations, and review-before-write proposals. Clean-machine acceptance and broader distributable packaging remain active work.

## License

Workwall is free software released under the [GNU General Public License, version 3](./LICENSE).