Skip to main content
A Condor Agent is a folder on disk plus a tick loop in memory. The folder holds the agent’s identity, its playbooks and its tools. The tick loop reads that folder, asks an LLM what to do, and acts through Hummingbot executors and bots behind a risk gate. This page covers where to put an agent so Condor loads it, what goes in the folder, and what happens on each tick.
Diagram of a Condor Agent: the stock agents/ folder and the local .condor/agents/ folder merged file by file; the agent folder with AGENT.md, loops, skills, routines, controllers and the files Condor writes at runtime; what the LLM sees on each tick; and one tick flowing from reading state through the risk checks, the LLM and the risk gate to the Hummingbot API and the journal, with the Dry Run, Run Once and Loop modes

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.
The rules Condor follows when it loads agents:
  • An agent is a folder with an AGENT.md in 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 example my_scalper. The name condor is 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.
Name each loop folder after the loop. Condor lists loops by folder name but writes their sessions to a folder derived from the name: in loop.md, lowercased with spaces turned into underscores. A loop named My Loop must live in loops/my_loop/. If the two differ, sessions are written somewhere other than the playbook’s folder.
Two shared folders sit beside the agents in either root:

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:
risk_limits only accepts the fields listed under Risk engine. Any other key under risk_limits is silently ignored. Put loop-specific limits, such as a minimum wallet balance, at the top level of default_config and enforce them in the loop instructions instead.

SKILL.md

Skills are not loaded into the prompt automatically. The prompt lists each skill’s 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 Pydantic Config class and an async run function. It uses the same format as Condor’s general routines:
An agent can run its own routines and everything in _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

  1. Read the state. Condor fetches this session’s executors, held positions and any drift between Condor’s records and the exchange.
  2. 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.
  3. 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.
  4. Run the LLM. The agent reasons and calls tools. Every tool call that could move money passes through the risk gate first.
  5. 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 in default_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_quote is above max_position_size_quote or 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 to loops/<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:
The Runs tab of the Market Making Expert, showing a dry run's agent response

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_builder skill 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.md and, optionally, a loops/<loop>/loop.md. Reload the Workspace and the agent appears under Agents.
To share an agent with the Condor project, ask Condor to publish it (manage_agents publish). That copies it into the stock agents/ folder, where it can be committed.
To move your agents, sessions and memory to another machine, copy the whole .condor/ folder.