Skip to content
AI & Agents
Back to writingAI & Agents

Building a Software Factory for AI Coding Agents (Codename: Diwan)

How I am building Diwan, a self-hosted software factory that plans, assigns, supervises and verifies the work of AI coding agents like Claude Code and Codex, in Arabic and English.

I use AI coding agents every day: Claude Code, Codex, opencode, Gemini. Each one is good. Running several at once is not.

So I am building a software factory for them. Its codename is Diwan (ديوان). Work goes in at one end as a plan; agents build it on my own machines; and it comes out the other end as reviewed, tested change requests that I approve, from my desk or my phone.

The problem: many agents, no factory

On a normal day I start a handful of agents on real tasks: Claude Code, Codex, opencode and others. Each one then runs its own subagents, so a few tasks quickly become many parallel sessions across work and personal projects. Today that looks like this:

  • A terminal per agent, and no single place that shows what each one is doing.
  • An agent hits its usage limit mid-task, and the work waits until the quota resets, even when another agent has credit to spare.
  • Away from the desk, I cannot answer an agent’s question or approve a change.
  • Skills, rules and plugins are configured separately for every agent.
  • There is no central view of tokens and credits used or left.
  • “Done” is a claim, not a fact. An agent says a task is finished, and I have to check whether it really is.

None of these is a model problem. The models are fine. What is missing is the factory around them: the line that plans, assigns, supervises and verifies.

Why a factory, not just an office

A diwan was the office where the work of the state was recorded, assigned and decided. That is where the codename comes from. But recording and assigning is only half the job. A factory also has a production line, quality control and a supervisor who never gets tired.

Diwan works like that:

  • Orders: work goes on an Agentic Scrumban board as epics, stories and tasks with acceptance criteria.
  • Production line: a deterministic dispatcher hands ready tasks to the right agent. Any agent can pick up any task.
  • Shift changes: when an agent hits its limit, it leaves a checkpoint commit and a handoff note, and another provider continues. The target is a median stall under 2 minutes.
  • Quality control: nothing reaches me without green CI, a review by a different agent, and evidence for every acceptance criterion.
  • Floor manager: every action, from starting a run to merging, has a mode I set: Off, Ask, Notify or Auto. The system enforces it, not a line in a prompt.
  • Control room: a Mac app, an iPhone and iPad app, and Telegram, so any approval takes under 30 seconds from my phone.

It does not replace the agents, GitHub or GitLab. It sits above them and gives them a shared memory, a supervisor and a set of rules.

A real software factory, end to end

Diwan works like a real software factory. It follows a full, modern development lifecycle from idea to release: requirements, design, planning, building, testing, security review, change requests and release. Every stage has automated tests, and code is written to the OWASP Secure Coding Practices.

That makes it useful whoever you are:

  • Developers and software engineers get a supervised team of agents that follows the practices they would insist on themselves.
  • Vibe coders can bring just the idea. In autonomous mode, Diwan takes ownership of turning it into a real product, and it is designed to avoid most of the bad practices that usually only years of experience across many teams and fields would catch.

Either way, you stay in control. You choose how much runs on its own, every step and its progress are visible, and you can step in at any point to make sure the result is the product you expected.

The whole line: from design to proven

A factory is not one machine. Diwan is designed to run the whole line, with each stage handled by the right agent and each result checked before it moves on:

  • Design: agents read the Figma design system and screens through MCP, so what they build matches what was designed.
  • Plan: a Planner breaks work into tasks with acceptance criteria and expected file paths, so two tasks that would touch the same files never run at the same time.
  • Build: Claude Code, Codex, opencode, Gemini and other CLI agents work in isolated sandboxes, each free to run its own subagents.
  • Terminal: agents run builds, scripts and tools inside their sandboxes, and you watch the live output without keeping a terminal open.
  • Test: a QA agent runs unit tests and end-to-end tests for websites and native apps, and attaches the results as evidence for each acceptance criterion.
  • Secure: a Security agent checks for exposed secrets, injection, authentication flaws and risky dependencies, following the OWASP Secure Coding Practices.
  • Review and ship: a second agent reviews the work, CI must pass, and the change request comes to you to approve.

Scale is set by your accounts, not by the tool: each provider account has its own limit on parallel sessions, and the dispatcher keeps every one of them busy.

A look inside

The desktop app is fully designed. These are screens from the Figma file, with the sample data I use for testing.

Home answers “what needs me?” first: a change request to approve, a question from an agent and a failed test, above the work that is running.

The Agentic Scrumban board: each card shows its agent, progress and cost. One task was handed from Claude to Codex when Claude reached its limit.

A live run: a timeline of what the agent did, its tests, the checkpoint commit, and acceptance criteria ticking off as evidence arrives.

An approval with its evidence: CI passed, the reviewer approved, all five criteria have evidence, and the diff and cost are right there before you decide.

Usage across every provider account: cost, tokens, handoffs, and which accounts are active or cooling down.

Ask Diwan: when Claude reached its limit mid-answer, the Assistant continued with Codex and said so.

On a Mac, the Diwan Notch keeps the factory in view without opening the app. It sits at the top of the screen and shows what is running, what needs you and how far each process has got.

The Diwan Notch: agents running now, a question waiting for you, repository setup in progress, and tests checking your changes.

The rules the factory never breaks

Before any screen or line of code, I wrote down ten principles. When convenience and a principle disagree, the principle wins. Five of them shape almost everything:

Agents are disposable; state is not. The truth lives on the board, in git and in a handoff note, never inside an agent session. An agent can die, run out of credit or be replaced without losing work.

The supervisor is code, not a chat. Assignment, retries, failover and budgets are decided by deterministic code on a workflow engine. Language models are called for judgement, and the code validates what they return. No “manager agent” can run out of credit and stall the line.

Agents can never raise their own permissions. An agent may propose a policy change. The change itself is an action that always asks me.

Verification over trust. Done means CI green, a review by a different agent (ideally a different provider), and evidence linked to every acceptance criterion.

Attention first. Every screen answers three questions in order: what needs me, what is running, and what changed since I last looked.

Architecture: three planes

Clients only show and control. The control plane is the single source of truth. Runners on your own machines do the work.

  • Clients (Mac, iPhone and iPad, web, CLI, Telegram) hold no business logic and never talk to each other, so they always show the same thing.
  • The control plane is a Fastify API with REST and a WebSocket stream, PostgreSQL for state, and Temporal for durable workflows. Timers, approvals, retries and failover survive restarts.
  • Runners run the agent CLIs in isolated git worktrees, enforce runtime policy, and connect outbound to the control plane. Code and provider keys never leave them.

Each agent sits behind one adapter interface, and every adapter must pass the same contract test suite. That is what makes agents interchangeable: moving a task from Claude Code to Codex changes nothing about how I plan or review it.

Everything that happens is an event in an append-only log, numbered without gaps. A phone that drops its connection picks up exactly where it left off.

On a Mac it runs without Docker; on a VPS or homelab it runs in Docker Compose. Either way it is reachable only over Tailscale, with no public ports.

Security: one owner per factory

  • Policy is enforced twice: by the workflow engine and again by the runner, through agent hooks, a sandbox and command allow-lists.
  • Provider keys and git credentials stay in the OS keychain on each runner. The control plane keeps metadata, events and the diffs needed for review.
  • What the server must hold, such as code-host tokens and the two-step secret, is encrypted at rest with AES-256-GCM.
  • Passwords are hashed with argon2id and checked against known breached passwords. Passkeys and an optional two-step code come on top, and every device has its own session that locks when idle and can be revoked.
  • Until sign-in lands, the server refuses to listen on anything but the local machine.

Arabic and English from day one

Most products add Arabic at the end, and it shows. In Diwan, every screen is designed in four versions: English light and dark, Arabic light and dark.

  • Arabic copy is natural Modern Standard Arabic, not translated English, with a glossary that gives every concept one name in each language.
  • Layout mirrors for Arabic, while code, paths, task keys and costs stay left-to-right, using Unicode bidi isolation. A test fails the build if an Arabic message leaves an example unisolated.
  • Every count uses all six Arabic plural forms.
  • Geist for English and Readex Pro for Arabic, from one set of design tokens shared by the web and SwiftUI apps.

How the factory is being built

Diwan is being built the way it will be used: AI agents do most of the work, under rules and reviews.

Spec first. Before any code there were 21 design documents and 13 architecture decision records. Every screen and line of code traces back to one of them.

Design first. The whole desktop product was designed in Figma before the first commit: a design system and 15 desktop screens with every state, each in four language and theme versions. Design tokens in code are generated from Figma.

Evidence, not claims. Each task gets its own branch, a written plan, and evidence for every acceptance criterion. A separate reviewer that has not seen the work checks it before I do.

The reviews catch real problems. Three examples, all caught before merge:

  • An Arabic error message that displayed http:// as //:http on screen.
  • A server that could have accepted connections from the network before sign-in existed.
  • A two-step secret stored as plain text in a schema draft.

How it compares

Several good tools already cover parts of this. I compared seven of them, using only what each vendor says on its own pages.

Checked 8 November 2026. Diwan’s column shows what it is designed to do; it is still in development.

Cursor and GitHub Agent HQ are strong and available today. Both centre on their own platform and subscription, and their cloud agents run on their infrastructure. Neither hands a task to another vendor when one hits its limit.

Devin and Factory are autonomous agents built for teams and enterprises, and each brings its own agent. Diwan supervises the agents you already pay for.

Conductor and Vibe Kanban are the closest in spirit: parallel agents in git worktrees on your own machine. Neither describes a policy layer, evidence gates or automatic handoff. bloop, the company behind Vibe Kanban, shut down in April 2026; the project continues as community-maintained open source.

Omnara is a good remote control for agents from your phone, but not a planner or a supervisor.

Diwan’s bet is the combination: any agent, on your own machines, under rules you set, with proof before anything reaches you, in Arabic and English. The honest gap is that the others ship today and Diwan does not yet.

Sources: Vibe Kanban (shutdown notice), Conductor, Cursor, GitHub Agent HQ, Devin, Factory, Omnara.

Where it stands

The desktop design is complete, and the foundation is being built now. Five Phase 1 tasks are merged: the monorepo and CI, shared API contracts that generate both TypeScript types and the Swift client, design tokens from Figma, the English and Arabic text catalogues, and the server with its event log and live stream. Owner sign-in is in progress.

  • Phase 0 · Design: desktop done; iPhone and iPad next.
  • Phase 1 · Foundation: in progress. Install, sign in, start Claude Code and Codex runs and watch them live with usage.
  • Phase 2 · Projects, board and Assistant: next. Automatic handoff on limits, change requests, and an assistant you can ask anything.
  • Phase 3 · Mobile and notifications: answer questions and approve work from iPhone and Telegram.
  • Phase 4 · Supervisor and quality gates: Diwan assigns and verifies work under your policies.
  • Phase 5 · Polish and breadth: skills registry, budgets, web client, more agents.
  • Phase 6 · Android: on hold until the rest is done.

I will share progress here as each phase lands, including the parts that go wrong.