README

Griglia

A Laravel + Livewire task board where you queue work for your coding agent and watch it happen:
requests, questions, progress, results — in your own application, on your own database.

Documentation · Quickstart · FAQ · Glossary · Changelog

What it is

You write a request as a task — a title, a note, sub-tasks, a screenshot — and mark it open to work. A CLI coding agent claims it, reports the phase it is in, asks when something is ambiguous, and closes it with a result you can read. Nothing is hidden in a terminal you were not watching.

A flow you can see — waiting → open to work → working → done, plus questions, pause, stop and resume. Every state is a dot on the row, and it moves live on every open device.
A CLI contract, not an integration — griglia:check to read and act, griglia:watch to react. Any agent that can run an Artisan command and read a Markdown file works: Claude Code, Codex CLI, Gemini CLI, …
Several agents, several lists — a default agent per list, an override per task, and a task claimed elsewhere is reported as busy instead of being taken twice.
Plans — turn one goal into a chain of tasks, where closing one opens the next.
It reaches you — an in-app bell, Web Push, mail, and live updates through any Laravel broadcaster.
It keeps the receipts — working time measured by the board, tokens and cost reported by the agent, results and answered questions kept with the task.
Yours to look at — installable themes, a settings page that tells the agent how to behave, and an instructions file assembled from switchable context blocks.

Requirements

PHP 8.3 or later, Laravel 12 or 13, and Livewire 4.4 or later
ext-gd, ext-fileinfo and ext-zip
a login route and an authenticated user in the default server mode — without any authentication the host application answers Route [login] not defined; GRIGLIA_MODE=local removes the requirement on a trusted machine
Tailwind CSS 4 only when choosing the optional vite asset mode

Optional integrations include laravel/ai for image descriptions, plans and transcription, and a Laravel broadcaster such as Reverb for live updates. Docker is not one of them: the board runs wherever your application runs, and the host scripts reach Artisan through a container only when one is there — see Run Griglia without Docker.

Install

From the root of the host Laravel application:

composer require alle80/griglia -W
php artisan vendor:publish --tag=griglia-config
php artisan migrate

-W allows Composer to resolve the Web Push dependency tree in a fresh Laravel application. The default precompiled asset mode requires no Node build. Publishing the config is optional but shows the keys worth deciding before the first migrate — starting with GRIGLIA_TABLE_PREFIX. Open / while authenticated: the board should load and create the first list for the user.

For access gates, local mode, optional integrations, asset alternatives and a complete verification, follow the installation tutorial. Then complete the quickstart.

Connect a coding agent

Publish the portable instructions from the host application root:

php artisan vendor:publish --tag=griglia-agents

Griglia can also generate those instruction files (AGENTS.md, CLAUDE.md, GEMINI.md) from the context you manage on /context. Generation overwrites them, so back up hand-written ones first — publish the host scripts and run python3 scripts/sync-context.py --backup; --restore undoes everything. See the installation tutorial.

Create or rename a list to match GRIGLIA_AGENT_LIST (dev by default), open a terminal in the project root — the directory with artisan and the instruction file — start your agent CLI there (claude, codex, gemini, …) and inspect the queue:

php artisan griglia:check

A session can be started in three ways — that terminal, a single non-interactive command, or a service that starts sessions by itself: see start the agent.

The board workflow is waiting -> open to work -> working -> done. The agent's first action is griglia:check --take=ID; it uses --ask=ID to pause for an answer and --done=ID to return its result. griglia:watch reports new work, answers and stop requests for interactive sessions. For unattended operation, use the persistent worker runbook.

Routes and access

The package registers /, /plans, /plans/new, /settings, /context, /stats, /agents and /dashboard (a redirect to the board, kept for old links). The dashboard path is configurable and can be disabled; without a home route it serves the board itself. In server mode, lists belong to the authenticated user; restrict access with canAccessGriglia() or GRIGLIA_ACCESS_GATE. Administrative pages use canManageGriglia(), GRIGLIA_ADMIN_GATE or GRIGLIA_ADMINS.

GRIGLIA_MODE=local removes authentication and makes lists global. Use it only on a trusted machine bound to 127.0.0.1; never expose local mode to a network.

See access and modes for the complete contract and the generated configuration and settings references for exact keys.

Front-end assets

Precompiled assets are the default and are published through Laravel's laravel-assets tag. If the host app must compile the package with Tailwind/Vite, publish the config, set GRIGLIA_ASSETS=vite, import the package CSS and JavaScript, and include package Blade files in Tailwind's sources. The canonical commands and trade-offs are in front-end assets.

Documentation


Documentation site	Everything below, in English and Italian
Quickstart	The first five minutes after installing
Using the board	States, modal, filters, archive
Start the agent	The three ways to run a session: terminal, one command, worker
The agent side	The command contract, workers, statistics
Features	Plans, notifications, themes, AI
Extending Griglia	Views, strings and languages, themes and styles, events, access hooks
Architecture	The task cycle, the tables, the seams — how the package is put together
Roadmap	What is coming, and what is out of scope by choice
FAQ · Glossary	Short answers, and the words used here
Upgrading · Troubleshooting	When a version moves, and when something breaks
Changelog	What changed, version by version
Versioning and releases	What a `0.x` version promises, and how a release is cut

Contributing and support

composer install
composer lint
composer test

Tests use in-memory SQLite by default and include a guard against destructive execution on a live database. Read CONTRIBUTING.md before opening a pull request — what a change must carry, how a bug report is written and what happens after — and the development guide before running Testbench or MySQL tests.

Griglia is maintained by one person on personal time: what that means for issues, pull requests and compatibility is written down in the governance and support policy. The project follows the Contributor Covenant 2.1 — direct reviews about the code, never about the person — and security reports go through SECURITY.md, not through public issues.

Credits

Griglia is written and maintained by Alessandro (alle80), with the help of the coding agents that use it every day — and it is developed on the board itself.

It stands on Laravel, Livewire, Tailwind CSS, spatie/laravel-settings, laravel-notification-channels/webpush, league/commonmark, SortableJS and Material for MkDocs for this documentation. Their licenses, and what they cover, are listed in license and third-party components.

License

Griglia is released under the MIT license: use it, change it and ship it in a commercial product, keeping the copyright notice. What that means in practice, which third-party licenses come with it and under which terms contributions are accepted: License.

alle80 / griglia

Maintainers

Package info

Statistics

Security