
Where Condor looks for agents
Condor reads agents from two folders and merges them:<condor> is the folder you installed Condor into. .condor/ is ignored by git, so nothing you create there is touched by an update.
You can move either folder with an environment variable:
CONDOR_AGENTS_ROOT for the local folder and CONDOR_STOCK_AGENTS_ROOT for the stock one. CONDOR_RUNTIME_ROOT moves the whole .condor/ directory. See Configuration.- An agent is a folder with an
AGENT.mdin it. Any directory directly under either root counts, unless its name starts with_. - The folder name is the agent’s ID. It appears in the Workspace URL (
/agents/<slug>), in Telegram (/agent <slug>) and in loop IDs. Use lowercase letters, digits and underscores, for examplemy_scalper. The namecondoris reserved for the default assistant. - Local wins, file by file. If both folders contain the same file for an agent, Condor uses the local copy. Files you haven’t overridden still come from the stock folder, so you keep receiving upstream improvements to everything else.
- Editing a shipped agent never changes the repo. The first time you (or an agent) edit a stock file, Condor copies that one file into
.condor/agents/<slug>/and edits the copy. - Shipped files can’t be deleted. An update would bring them back. You can mute a shipped skill or routine instead, which removes it from the agent’s runs.
- No restart needed. Agents and loops are read from disk each time Condor needs them, so a new folder appears the next time you load the Workspace.
Folder structure
Everything an agent needs lives under its folder. Entries marked (Condor) are written by Condor at runtime; don’t create them yourself.The pieces of an agent
One agent can own several loops. They share the agent’s skills, routines, controllers and memory. For example, the Market Making Expert has a PMM Mister Operator loop and a HIP-3 MM Operator loop.
AGENT.md
YAML frontmatter followed by the agent’s identity and domain knowledge in Markdown.loop.md
Frontmatter with the loop’s settings, followed by the instructions for each tick.
The session settings
default_config accepts:
SKILL.md
name and when_to_use, and the agent reads the full skill when it needs it.
Routines
A routine is a Python file with a PydanticConfig class and an async run function. It uses the same format as Condor’s general routines:
_shared/routines/. It cannot run Condor’s general routines in the repo’s top-level routines/ folder.
Controllers
A controller folder holds Hummingbot V2 controller code (<name>.py), a CONTROLLER.md describing it, and optional sample configs. The folder name must be a valid Python identifier, and no sample config may be named config.yml.
The CONTROLLER.md frontmatter sets the controller’s category, which decides where it is installed on the server:
type is one of directional_trading, market_making or generic. The agent page’s Controllers tab shows whether each controller on the server matches the agent’s copy.
What happens on each tick
- Read the state. Condor fetches this session’s executors, held positions and any drift between Condor’s records and the exchange.
- Check the limits. It computes exposure, executor count and drawdown. A soft drawdown breach skips the tick and notifies you; a hard breach starts an emergency shutdown.
- Build the prompt.
AGENT.md, the loop instructions, the list of skills and routines, the current config, the risk state and the market data go into one prompt. - Run the LLM. The agent reasons and calls tools. Every tool call that could move money passes through the risk gate first.
- Record it. Condor appends to the session journal and saves a full snapshot of the tick.
Risk engine
Each loop session has these limits. Set them indefault_config.risk_limits or in the Start dialog.
The risk gate also always refuses:
- Direct orders:
place_order. Agents trade through executors and bots. - Other sessions’ executors: creating executors that don’t carry this session’s ID, and stopping executors owned by another session. The exception is executors adopted from a stopped session of the same loop.
- Over-sized bots: a bot deploy whose declared
max_global_drawdown_quoteis abovemax_position_size_quoteor at or above the capital it trades, or whose controllers would trade more than the session’s remaining position allowance. - Anything in a Dry Run: every action that would change state, plus running code and routines.
Each Loop run gets its own session ID. When a stopped loop starts again, the new session adopts the executors the earlier session left running: they appear in its tick data as
adopted_executors, and it can stop them. Held positions from keep_position=true stay with the earlier session, and Run Once executors are never adopted. See Sessions.Stopping a loop
The shutdown policy in
shutdown.md is one of:
keep_spot_close_perp(the default): keep spot holdings, close perpetual positions.flatten_all: close everything.keep_all: stop executors but keep every position.
Sessions, journals and learnings
Each Loop run writes toloops/<loop>/sessions/session_N/:
Dry Run and Run Once don’t create a session. Each writes one file to
loops/<loop>/dry_runs/experiment_N.md.
loops/<loop>/learnings.md carries lessons across sessions, in Market Observations, Execution Notes and Retired Insights sections. It is capped at 20 entries. You can edit it by hand; the agent treats your entries like its own.
In the Workspace, the agent page shows all of this under Runs:

Creating your own agent
There are two ways to create an agent:- Ask Condor. In the Workspace chat or Telegram, describe the agent you want. Condor’s
agent_builderskill writes the folder for you, either from a description or from a folder of your own controllers, configs and notes. See Agent Builder. - Write the folder yourself. Create
.condor/agents/<slug>/AGENT.mdand, optionally, aloops/<loop>/loop.md. Reload the Workspace and the agent appears under Agents.
manage_agents publish). That copies it into the stock agents/ folder, where it can be committed.

