Build with coding agents

Cursor, Codex, and Claude Code

Rails Agent is git-native: external coding agents edit app/agents/ and push with the CLI. The dashboard owns OAuth, channel installs, memory, budgets, and guardrails. Start every session by reading AGENTS.md.

1 · Read AGENTS.md first

After install, the gem and docs point coding agents at AGENTS.md (repo root or docs/AGENTS.md). That file is the onboarding contract: taxonomy, progressive path, Library rules, BYOK model DSL, and what not to do (no cloud pull authoring).

shell

# In the Rails app (or rails-agents gem checkout)
open docs/AGENTS.md
# or: AGENTS.md at the app root after install

Public mirror of the same guidance: Getting started.

2 · Agent directory layout

One folder per agent under app/agents/<slug>/. Shared reuse lives in app/agents_library/ and is attached through imports.yml.

tree

app/agents/store_assistant/
├── agent.rb
├── prompt.md
├── imports.yml
├── tools/
├── skills/
├── packages/
├── knowledge/
├── connectors/
├── channels/
└── evals/

3 · Sync, run, deploy

Coding agents should prefer the CLI over inventing HTTP calls. Full command reference: CLI.

shell

$ bundle exec rails-agents run store_assistant \
    "Where is order ORD-DEMO-1001?" --session user-42
$ bundle exec rails-agents sync store_assistant
$ bundle exec rails-agents deploy store_assistant
$ bundle exec rails-agents logs store_assistant
$ bundle exec rails-agents evals store_assistant

4 · Repo vs dashboard

Split work deliberately so coding agents do not try to fake OAuth or paste provider secrets into the repo.

Coding agents do this in the repo

Work	Where	Notes
Agent class & prompt	agent.rb, prompt.md	Taxonomy base class, model DSL, tools, skills, knowledge globs.
Tools & skills	tools/, skills/	Ruby actions and multi-step behaviors; keep secrets out of code.
Packages & knowledge	packages/, knowledge/	Registry installs and grounding docs; Library via imports.yml.
Channel stubs	channels/	Declare kinds in code; complete OAuth / install in the dashboard.
Evals	evals/*.yml	Golden cases for sync / deploy confidence.
CLI lifecycle	rails-agents sync \| run \| deploy	Push files, smoke-test, ship — see the CLI guide.

Humans (or agents with browser access) do this in the dashboard

Work	Why dashboard
Connectors OAuth	Notion, Sheets, HubSpot, Composio email, and other SaaS — tokens never enter Git.
Channels install	Open-Wire Slack / Teams installations, inbound webhooks, live channel enablement.
Memory toggle	Build → Memory enables managed Mem0 conversation memory (on by default for new agents).
Budgets	Spend limits and usage visibility under Budget / guardrail policies.
Guardrails	Model access, prompt injection, sensitive info — create policies and attach to agents.
BYOK credentials	Settings → Providers; reference as credential: :company_openai in agent.rb.

5 · Prompting tips for coding agents

Point the agent at AGENTS.md and the target slug under app/agents/.
Prefer Knowledge + one read-only tool before Workflow / Operations.
Use credential: :symbol for models — never hardcode API keys.
After edits: sync, then run with a fixed --session when testing memory.
Leave connector OAuth, channel install, budgets, and guardrails as explicit “open /agents” follow-ups for the human.

CLI

sync, run, deploy, logs, and evals.

CLI reference →

Memory

Conversation memory DSL and Mem0.

Memory guide →