Your agents. Your methods. Your choice of engine.
Français · Reference manual, in French
Berger gives agents a working identity, memory, checklists and scheduled tasks through plain files that you own. It runs the official Codex and Claude Code CLIs with their subscriptions. Herdr provides the workspaces, panes and status views.
Keep your methods when you change engines. The supported engines are Codex and Claude Code; an arbitrary provider adapter is not part of this project. Berger does not call a model provider API directly.
Use a new installation in ~/berger; do not overwrite existing data or links.
There is no bundled dependency installer. The short English installation
guide explains the manual steps and troubleshooting.
- Linux, Git, Bash, Python 3.11+ (
tomllib), Herdr 0.9+. - Codex and/or Claude Code, signed in, in a covered version.
- Working bubblewrap, GnuPG and systemd user services.
- Herdr available at
~/.local/bin/herdr, as expected by the supplied units.
Check the sandbox with bwrap --ro-bind / / --dev /dev --unshare-net true.
On Ubuntu 24.04+, an administrator may need the bubblewrap AppArmor profile in
the reference. A strict agent refuses to
start without its sandbox.
Clone the repository, then work from its root:
git clone https://github.com/lugio/berger.git ~/berger
cd ~/berger
cp config.exemple.toml config.toml
cp commun/modeles/USER.md commun/USER.md
mkdir -p ~/.local/bin ~/.config/systemd/user
ln -s "$PWD/bin/berger" ~/.local/bin/berger
ln -s "$PWD/courtier/berger-outil" ~/.local/bin/berger-outil
export PATH="$HOME/.local/bin:$PATH"Before continuing, edit config.toml: set proprietaire to your name and
review coffre, masques, masques_si_presents and masque_fichier for your
machine. The copied example supports a first agent without external tools;
its tool declarations are commented out and it supplies no custom guard.
Keep credential storage protected and local configuration out of Git.
Complete commun/USER.md with whom the agents work for.
berger nouveau assistant "Assistant"Expected: agent créé : followed by agents/assistant's absolute path.
Edit agents/assistant/SOUL.md to define its role, capabilities and limits.
Set heures = aucune in agents/assistant/agent.conf to run only on request.
The default engine is Codex. For Claude Code, set both moteur and panneaux
to claude and use its authenticated CLI instead of the Codex login below.
Then regenerate the settings; Codex login requires an interactive sign-in:
berger regenerer
CODEX_HOME="$HOME/berger/.codex" codex login
cp systemd/* ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now berger.timer berger-courtier.service berger-herdr.service
berger espace assistant
berger espace ensemble
berger etatExpected: an Assistant workspace with its conversation and a Berger workspace
showing the agent state. Ask it to introduce its role; it should reflect SOUL.md.
Review engine hook approval prompts. The first launch of an engine version runs
its admission contract (up to 20 minutes); rejection can trigger fallback to
another admitted engine, or refusal if none is admitted. See
which tests to run and
security.
Login, local configuration, approval and admission are required manual steps.
| Capability | What it does | Guide, in French |
|---|---|---|
| Portable agent methods | Identity, instructions and working files stay on disk | Principles |
| Engine choice | Run Codex or Claude Code through their official CLIs | Commands |
| Memory and work tracking | Journals, tasks, checklists and proposed long-term memory | Herdr views |
| Agent workspace layout | Per-agent espace.toml, validated proposals and automatic application without restarting the conversation |
Workspace layout |
| Scheduled work | Heartbeats and tasks driven by the user timer | Operations |
| Brokered tools | Declared verbs and configured human approvals | Broker |
| Missions and teams | Delegate scoped work and review changes before merging | Development teams |
| Shared deliverables | Agent and project libraries, with access boundaries | Library |
| Optional web views | Read-only views of the same operational data | Web interface |
| Configured backups | Encrypted archives for installation data | Backups |
The interface is in French, with five tabs (Home, Decisions, Board, To read, Behind the scenes); the data below is fictional (demo views guide).
Home: red and yellow alerts, what waits for a decision, board and agents.
Board: agents, approvals and merges, in columns.
Behind the scenes, broker panel: permissions, writes awaiting approval and calls.
The host, the broker and configured tool adapters are trusted components.
Strict agents use generated permissions and sandbox settings for their engine.
An agent configured with mur = ouvert must not be treated as isolated.
Engine versions must pass their admission contract before strict use. A passing model-free suite is not an engine admission result. Tests establish measured behavior; they are not a universal security guarantee. Hooks, temporary directories, MCP relays and host restrictions have documented limits.
Credentials belong in the configured store outside the agent's readable files. Broker filtering and declared approvals help control access; review the actual permissions and tool implementation for your installation. Agents can write inside their allowed working areas. Long-term memory changes are proposed for review rather than silently consolidated.
See SECURITY.md for private vulnerability reporting. Do not put real credentials or personal agent data in issues or pull requests.
Herdr hosts the workspaces; Berger prepares the agent and its engine profile.
Tool requests go through the file mailbox to the trusted broker.
The broker checks the declared verb, obtains approval when required and invokes
the configured adapter. Results return through the broker to the requesting agent.
A view, a command or an engine is one dropped file (core API, bin/noyau/api.py); a broken module is set aside and named by berger etat.
Agent files ----> Berger ----> official CLI
^ |
| v
Herdr agent work
|
file mailbox (berger-outil)
|
trusted broker
(approval when required)
|
configured tools
This diagram is generated by python3 docs/scripts/schema.py --write. Use --check to detect drift without changing files.
It shows the core tool-request path; optional web and MCP flows are in the manual.
| Document | Purpose |
|---|---|
| French reference manual | Full installation, commands and operations |
| Configuration example | Installation settings and tool declarations |
| Master setup | Configure the coordinating agent |
| Contributing | Spec, tests, gates and independent review |
| Security policy | Private reporting and scope |
| Code of conduct | Community expectations and moderation |
| Changelog | Documented version history |
| Roadmap | Planned work and the state of the modular refactoring |
The full manual remains in French; both entry points link to the same reference.
Back up agent data, configuration, libraries and credentials before removing them.
Use encrypted storage for backups containing secrets.
Finish or stop active agent work before stopping the services.
Inspect the units you enabled with systemctl --user list-unit-files 'berger*'.
Stop the core services and scheduler installed by the quick start:
systemctl --user disable --now berger.timer berger-courtier.service berger-herdr.serviceAlso disable optional berger-tests.timer and berger-interface.service if enabled.
Remove the local berger.reprise plugin link using your Herdr version's plugin help
(herdr plugin --help) so a later Herdr start will not resume Berger agents.
Remove only the user unit files and command symlinks you added for Berger,
then reload user units with systemctl --user daemon-reload.
Delete the checkout and private data only after checking your backups.
Removal is manual; Berger does not provide a universal uninstall command.
Start with CONTRIBUTING.md and a small spec for substantial changes.
Bug fixes need a reproduced failure, a root cause and a regression test.
Run verify, tests and pret; the contribution guide gives the exact commands.
The prepared CI workflow uses a fresh local clone with an isolated home directory.
It does not replace real-engine admission tests.
Berger is distributed under the MIT license. The current documented version is 0.3.0; earlier versions are listed there too. Engine subscriptions, Herdr and external tools have their own terms and licenses.