The Agence CLI allows for powerful command routing functionalities, enabling seamless interactions with various operations. —
For chat mode , Agence implements itself both as a $GIT_REPO/CLAUDE.md and $GIT_REPO/.github/copilot-instructions.md . It is intened to be parsed in your agentic system or IDE of choice but at the moment this early version is VScode ready.
The minute you install agence from the README.md instructions you are ready to begin.
Simply instruct your Chat prompt to read teh 2 .md files and acknoweledge the new context. Afterwards this become easier via ^init and ^reload agence commands.
The agence command set is designed to work both from prompts and from CLI using agenc command.
NOTE: All Agence commands like “^init” are meant to ALSO be seamlessly interpreted by your agentic prompt.
So you can both in chat prompt state
in a prompt you can issue :
"Good morning. ^init , ^reload and ^resume , then acknowledge context"
which is the same as in shell :
bin/agence ^init
agence ^realod
agence ^resume"
Once you have loaded agence you can use
agence ^help
The Agence CLI allows for powerful command routing functionalities, enabling seamless interactions with various operations.
Before you begin, ensure:
bash
git clone https://github.com/l-agence/agence.git
cd agence
bash
curl -fsSLo shellspec https://git.io/shellspec
chmod +x shellspec
Agence organizes commands into five prefixes that determine their behavior. You can use these prefixes to interact with agents, run workflows, or invoke external tools.
| Prefix | Purpose | Example |
|---|---|---|
^ |
Universal AI commands: Shared, knowledge context for agent collaboration. | ^plan, ^deploy, ^learn |
~ |
Private commands: Operating in local/private scope. | ~reload, ~commit |
! |
Shell launcher commands: Calls external tools like bash or Aider. | !bash, !aider, !git |
/ |
External commands: Delegates commands to underlying systems like Git or Terraform. | /git status, /terraform-plan |
@ |
Routing qualifiers: Directs commands to agents, projects, or organizational targets. | ^plan @project, ~commit @ralph |
^)In agence we Use ^as a prefix for agence internal commands in a shared (shard based) collaborative context. Use this mode for tasks that engage agents or invoke AI-powered planning when sharing to the team.
In agence we picked “^” In order to support the maximum number of tools and avoid collisions with others. In addition the “^” symbold denotes both Aleph for teh first letter of Agent and AI as well as it invokes similarity to lambda execution.
Example:
agence ^plan
agence ^learn
agence ^reindex
agence ^sync
agence ^commit ; agence ^push
Example Workflow:
agence ^refactor @module
~)In agence , we Use ~ to denote Ai powered commands that act in a private context. Private includes ~todos and ~notes which are always personal and never shared directly to the shared shard without user request. These execute commands in offline/local-only contexts.
Agence segregates derived world model into shared team knowledge (knowledge/) and private knowledge (knowledge/private/). This allows you to store tests, failures etc privately per repo in local filesystem without polluting or leaking to the team.
~commit @myproject
Explanation:
!)In agence we Use ! to invoke a shell or an external agent tool. This is used alos to launch sub agents like !aider or !ralph or !pilot . Effort has been made to support and avoid collisions with your own tooling.
!bash
!aider
!git status
/)in Agence we use “/” prefix to denote an external command. These can be both standard tools ( git, gh, jf, terraform, aws cli, etc) as well as passing or respecting other MCP and agentic tooling commands.
Run external system tasks (validated against commands.json):
/git status
/terraform-plan
@)Agence uses “@” as a universal command routing suffix. This is used both to target destination agents, models, security tiers BUT also to determine target orgs, teams and projects. In addition a symlink bearing the name of “@” in a knowledge tier is used to set the default routing entity. The “@” symbol is always git ignored allowing users to set their routing context without risk to others.
The @ symbol directs commands to specific agents or contexts:
^commit @ralph routes to the agent named Ralph.^plan @acme.tld.For example in getting started, you should create a folder called
mkdir -p knowledge/<domain.tld>
ln -s knowledge/<domain.tld> knowledge/@
mkdir -p knowledge/private/<domain.tld>
ln -s knowledge/private/<domain.tld> knowledge/private/@
From that point on you can start to populate these with the required .md and json files :
Let’s tie it all together with an example:
^plan @project-a
~commit @team-x
/git pull origin main
!aider
Agence includes a ShellSpec testing framework to validate your workflows. To run tests:
tests/ directory:
cd tests
./shellspec
./shellspec spec/command_routing_spec.sh
AGENTS-ROUTING.md.ARCHITECTURE.md.AIPOLICY.md.While Agence enforces strict routing rules (e.g., via EBNF grammar for AIPOLICY), AI interpreters like Copilot and Aider are quite forgiving. Even if commands deviate slightly, Agence agents can often resolve intent through context or conversation.
^help deploy strategy
While this isn’t an exact match to EBNF, the agent may infer that ^plan with relevance to “deploy strategy” is intended.
Try creating a new repository shard for testing:
git clone https://github.com/l-agence/agence.git agence-shard
cd agence-shard
Run commands, interact with agents, and customize workflows. Experiment with handoffs between agents, and extend the ShellSpec tests as needed.
This guide helps you:
^, ~, !, /, @).Agence emphasizes a tool-agnostic approach, which means that it can work with various tools without being tied to a specific technology or platform. This flexibility allows you to choose the best tool for your needs without restriction.