Give AI your project, not just your prompt.
Your coding agent writes code fast. Then the next session forgets your project, and it says "done" without proof.
YallaFlow fixes that. It gives Claude Code and Codex a reviewed memory of your codebase, a workflow sized to each request, and evidence before anything is called done. A local console, in English and Arabic, lets you watch every request move and start your app with one button.
Install in 1 minute · Visual tour · الجولة بالعربي · Website · Docs
- Project understanding. A reviewed, durable memory of your codebase, so a new session never starts from zero.
- The right workflow. A bug, a feature, and an investigation each get a lifecycle sized to the work.
- Evidence. "Done" means verified and checked against what was asked, not just "the agent said so".
- Your app, one button. The agent works out how your project runs. You trust it once, then press Start project.
- Run work your way. Start one task now, or queue several to run one after another. You stay in control of every approval.
It runs locally, sends no telemetry, and keeps everything in your repository.
yallaflow console opens a local web app in Arabic or English, light or dark. It shows every project, every request and every running service on one screen. Nothing runs on its own, and nothing leaves your machine.
Create work in your own words. Write the request the way you'd tell a colleague, and attach a screenshot or a BRD if you have one. Your agent takes it from there. |
Watch every request move. Each item moves through Understand → Decide → Change → Verify → Remember, and its % is computed from evidence. |
Set the project up with your agent. The agent works out how the project really runs, including Docker, vhosts and parent folders, and proposes a plan with its evidence. Its investigation is read-only and never touches secrets. |
Then just press ▶ Start project. One page shows the state, Start/Stop, the apps to open, and a row per service. Shared infrastructure is never stopped by mistake. |
The same console in Arabic, dark theme · نفس الكونسول بالعربي
 |
 |
 |
 |
Take the full visual tour → It goes from an empty folder to a running app in 12 screens. الجولة كاملة بالعربي ←
flowchart LR
n(["Node.js ≥ 20.16"]) --> i["npm install -g yallaflow"]
i --> p["cd your-project<br/>yallaflow init"]
p --> a["Open Claude Code or Codex<br/>and describe the work"]
p --> c["yallaflow console<br/>(optional, in your browser)"]
1 · Install the CLI (once per machine). Install it globally or in a tools prefix, never as a dependency of your app. Options →
npm install -g yallaflow
yallaflow --version2 · Connect a project (once per project), or create a new one from the console's New project wizard:
cd your-project
yallaflow init3 · Work. Open your agent in the project and describe the work, or open the console:
yallaflow consoleinit connects Claude Code (CLAUDE.md) and Codex (AGENTS.md) with a small pointer and keeps anything already in those files. Then open Claude Code or Codex in the project and describe the work. These are prompts for your agent, not terminal commands:
Fix invoice totals.
Build an anonymous employee survey platform.
You don't need to say "use YallaFlow", explain the architecture, or ask for specs and tests. Every session orients itself automatically.
On an existing project, the first request comes with one review step. The agent first builds an evidence-backed understanding of the codebase, without changing code. It shows you what it found and what it did not inspect, and waits for you to reply Approve. After that, your original request continues, and every later session and teammate starts from that approved understanding. More on first use →
flowchart LR
v["yallaflow --version"] --> u["npm install -g yallaflow@latest"]
u --> s["yallaflow upgrade status<br/>(read-only)"]
s --> r["yallaflow agent refresh<br/>once per project"]
r --> d["yallaflow doctor"]
d --> c(["Restart yallaflow console"])
YallaFlow never updates itself and never checks the network for versions. You decide when to upgrade:
npm install -g yallaflow@latest # or an exact version: yallaflow@1.5.1
yallaflow --version
# in each project
yallaflow upgrade status # read-only: what, if anything, needs attention
yallaflow agent refresh # only if the agent contract is reported outdated
yallaflow doctor- Your work is safe. Work items, project memory and sources are kept as they are, and nothing is migrated without a command you run.
- Restart the console after upgrading, so the browser loads the new version (
Ctrl-C, thenyallaflow console). - Teams: upgrade every machine and CI job that works on a Shared Project together.
Updating in detail → · Upgrading to 1.5.0 → · 1.4.0 → · 1.2.0 → · from 1.0.x: 1.1.0 →
flowchart LR
dev(["You<br/>describe the intent"])
agent["Coding agent<br/>Claude Code · Codex"]
yf["YallaFlow"]
mem[("Project memory<br/>facts · rules · decisions")]
flow["Workflow<br/>sized to the request"]
ev["Evidence<br/>verification · intent checks"]
out(["Verified change"])
dev --> agent
agent <-->|"orients · records"| yf
yf --- mem
yf --- flow
yf --- ev
agent --> out
The agent does the reasoning and the coding. YallaFlow keeps the durable state around it: what the project is, which workflow applies, and what has been proven. YallaFlow calls no AI model itself and sends no telemetry.
The complexity stays inside YallaFlow, not inside your prompt.
flowchart TB
subgraph decide["Decide"]
direction LR
req(["Request"]) --> route["Route<br/>bug · feature · change · …"] --> und["Understand<br/>memory + code"] --> spec["Specify & plan<br/>when needed"]
end
subgraph deliver["Deliver"]
direction LR
impl["Implement"] --> ver["Verify<br/>with evidence"] --> conv["Check against<br/>intent"] --> rem[("Remember")]
end
decide --> deliver
The depth adapts to the work. A bounded bug fix goes from root-cause analysis straight to the fix, while architectural work gets a reviewed design, specification, or plan. Nothing is called done without fresh verification evidence, and work that carries acceptance criteria is checked against them before it closes. What was learned becomes reviewed project knowledge. Workflows in detail →
A steadier console. Changelog →
- The console no longer re-renders every second after an agent finishes a task while its session stays open.
- A button in the agent chat's header enlarges the chat for following long conversations.
- Team mode (Shared Project Mode) on the Overview is a clear card: what it means, its status, the branches, and one button.
Queue your work, and stay in control of every approval. Changelog → · Execution modes →
- Run Now. One work item, one agent, right now. This is Start, as before.
- Queue. Pick several work items and they run one after another, each in a new agent session. The next one starts only when the current one is DONE and its session has ended. Anything that needs you pauses the queue, and the Agents tab controls it all.
- Parallel (off in 1.5.0). Each work item runs in its own lane, a Git worktree and branch beside your project, with its own agent. It stays off until a real-agent test confirms its security boundary.
- Review, then merge by hand. A finished lane shows readiness, the files it changed, conflicts, secret-looking content anywhere in its commits, and the exact Git steps to merge it yourself. A conflict is never resolved for you; you can send it back to the lane's agent. Automated Merge is off in 1.5.0 for security reasons and stays off until its checks can run safely.
- Safe by default. YallaFlow never pushes, rebases, resets or deletes branches, and in 1.5.0 it commits and merges nothing itself. Every Git command it starts turns off repository-configured fsmonitor, hooks and submodule recursion. Security →
- Approval wait. Choose how long a tool request waits for you: 5, 15, 30 or 60 minutes. When the wait runs out, the request is denied.
- Overview: your branch and Shared Project Mode. See the current branch and whether Shared Project Mode is on, and turn it on from there. Work items show their title first, with copyable IDs.
A console that works with you. Changelog →
- Start and let it run. «Start» on a work item opens the chat with one instruction for the whole job; the agent stops only for a decision only you can make, and one button shows what is needed: review, answer, or continue.
- See the agent from anywhere. A card and a call-out show when the agent needs your approval or reply; the chat says how long it has worked and its last step.
- Easier reviews and confirmations. Reviews read like documents and expand to full screen; typing names is replaced by a single tick everywhere.
- New projects. Progress while it is created, a «project ready» screen, the agent chosen in the wizard, a «Something else» stack, and a Start here card.
- Projects page. Remove a saved project and see each project's memory health.
- Claude Code on Team or Enterprise. The console warns that channels must be enabled by the organization, and reports messages Claude Code never started on.
Set the project up once, then run it from one page. See it →
- Ask the agent how the project runs. On Setup, the agent analyzes the project and reads its real configuration: Docker Compose, vhosts, and the folders above the project. It then proposes services, start order, ports and
*.localhostlinks, with confidence and evidence. The investigation is read-only, never opens.env, and marks what it can't verify as unresolved. The proposal arrives preselected. A quick scan without an agent is still there (yallaflow runtime analyze). - Run control first. Once services are saved, Setup becomes the Run page. It shows one state, ▶ Start project / ■ Stop project, Open links, and a row per service with Start, Restart, Stop and Logs. Configuration folds away beneath.
- Review and trust, once per service. Trust is bound to the exact command, folder and files you reviewed. Any later change ends it.
- Shared infrastructure is protected. A Docker stack or database that serves other projects is never stopped by Stop project. Stopping it is a separate, typed confirmation.
- A first-time setup guide for existing projects: scan the stack, choose services, choose agents.
- Work lifecycle. Put work on hold, resume it, or close it without delivery (
yallaflow work hold|resume|close). Closed work is never counted as done. - Manage work from the console. Run YallaFlow's own actions on a work item, make review-gate decisions with a note, and edit a request before work starts. Console →
- Project Overview. Stack from repository evidence, understanding from project memory, and guided onboarding. Run
yallaflow overviewor open the console's Overview tab. - Development runtime. Start, stop and watch your app's services from the console's Setup tab, after you review and trust them. Runtime →
- New Project Wizard. Plan a new project with an official generator, review the exact commands, then create it. New project →
- An agent chat that keeps work moving. The chat is on every console page: a work item page is that item's chat, and the other pages share a project chat. If an agent stops (for example, at a usage limit), the item offers to continue with another agent. Codex is supported, and Claude Code is available as an opt-in experiment. Agents →
- Agent Workspace (opt-in,
yallaflow console --agents): work with Codex from the console using your own ChatGPT subscription. You get chat, live activity, and tool-permission requests next to the Flow. No API keys, ever. Agent Workspace →
- A local console.
yallaflow consoleopens a browser view of your projects, in Arabic or English:- one action, Create work: a requirement in your own words and an optional BRD become a work item your agent continues;
- the flow from New to Done across five stations, with completion % computed by YallaFlow from evidence;
- what waits for you, and each item's next step;
- acceptance criteria with their verification evidence;
- attachments, Git worktrees, and insights from recorded data. Console →
- Safe for several agents. A workspace write lock means two agents in one checkout never overwrite each other's records or get the same ID.
- A read contract for scripts.
yallaflow snapshot --jsonandyallaflow work show <id> --jsonprovide versioned JSON.
Three optional capabilities. If you don't use them, nothing changes.
flowchart LR
ticket["Tracker ticket<br/>GitHub · Jira · Azure DevOps"]
subgraph life["Engineering lifecycle"]
direction LR
u["Understand"] --> c["Change"] --> v["Verify"] --> r["Remember"]
end
qc["AI QC<br/>Playwright"]
demo["Smart Demo<br/>optional video"]
ticket -. "optional input" .-> life
qc -. "only when you ask" .- life
demo -. "only when you ask" .- life
Connected requirements. Point the agent at an existing ticket. Its description, acceptance criteria, comments and attachments become a preserved source, and the requirements trace back to it. The agent fetches the ticket with the integration it already has. YallaFlow can also fetch it read-only, using a token from your environment that is never stored.
Implement acme/shop#42.
Work on SHOP-118 — https://acme.atlassian.net/browse/SHOP-118
AI QC. The agent plans functional and exploratory checks from the acceptance criteria, runs them with Playwright (CLI or MCP), and records what actually happened. A check counts as passed only if it was actually run and has evidence.
Check that cancelling a booking works in the browser.
Smart Demo. The agent proposes the few scenarios worth showing, in priority order. You approve them before anything is recorded, and video is optional.
Record a short demo of booking a pitch for the club owner.
Good to know
- QC and Smart Demo are off by default, independent of each other, and run only when you ask. They never start because a task finished.
- A demo shows scenarios working once. It is not proof that tests passed.
- Videos, screenshots, traces and generated reports stay on your machine and are Git-ignored by default. Only the lightweight
qc.json/demo.jsonrecords are committed. - Playwright must be available to your agent. Video recording also needs Playwright's ffmpeg (
npx playwright install ffmpeg).
Tickets, AI QC & Smart Demo guide →
A maintainer runs yallaflow init, approves the project understanding, runs yallaflow shared enable, and commits .yallaflow/. Teammates just git pull and open their agent. They need no YallaFlow commands and no join step, only a compatible yallaflow CLI. Knowledge learned on a branch travels with that branch. YallaFlow never pushes. It commits or merges only when you approve a Review & Merge in the console. Shared Projects →
Developers work with Git. Agents work with YallaFlow.
Day to day, you talk to your agent. These are for setup and for looking under the hood:
yallaflow init # once per project
yallaflow brief # what YallaFlow knows and what's in progress
yallaflow status # workflow state
yallaflow doctor # integrity check
yallaflow console # the flow in your browser; create work from thereEverything else is in the CLI reference.
The YallaFlow website, engmohamedamer.github.io/yallaflow, gives a one-page overview. The guides live in this repository:
| Guide | What it covers |
|---|---|
| Visual tour · العربية | 12 real console screens, from an empty folder to a running app |
| Using YallaFlow | the practical end-to-end guide: start here |
| Installation | install options, updating, legacy projects |
| Tickets, AI QC & Smart Demo | connected requirements, optional QC and demos |
| Shared Projects | one project understanding for the whole team, through Git |
| Canonical workflows | Greenfield, Brownfield, bugs, features, investigations, teams |
| Project memory | durable context, evidence and freshness |
| Console | the local browser view, Create Work, New project, Setup |
| Execution modes | Run Now, Queue, Parallel, Review & Merge |
| Development runtime | analyze, review, trust, start and stop your app's services |
| CLI reference | every command and flag |
| Architecture | internal concepts and design |
| Security | trust model, secret redaction, network boundary |
| Limitations | current boundaries |
| Releasing & compatibility | Semantic Versioning and the compatibility promise |
| Changelog | release history |
1.5.1 steadies the console of 1.5.0, which runs work your way: one task now, or a queue of tasks one after another, with review and manual merge for lanes. Parallel execution and Automated Merge are disabled in this release. 1.0.0 was the first public, stable release. YallaFlow follows Semantic Versioning and keeps existing workspaces readable (compatibility promise).
- Local-first. There is no YallaFlow server, account, or cloud service.
- Agent-agnostic, with first-party setup for Claude Code and Codex.
- No AI calls and no telemetry. YallaFlow touches the network only when you explicitly fetch a tracker ticket.
- Not a project-management tool, and not a bot that commits or pushes for you. It commits and merges only what you approve in Review & Merge, and it never pushes.
See Limitations for current boundaries, for example that Windows is not yet verified.
Agent reasons. YallaFlow governs. Project memory persists.
Give AI your project, not just your prompt.