fosm-rails-coding-agent

FOSM-aware runtime intelligence for Rails — MCP server + ACP agent for coding agents.

Gives coding agents (Claude Code, Codex, Copilot, OpenCode) runtime access to your Rails application: database queries, logs, code evaluation, and — when fosm-rails is present — deep introspection of FOSM lifecycle state machines, transitions, guards, and audit trails.

This gem exposes two complementary protocols:

┌─────────────────────────────────────────────────┐
│              Rails Application                   │
│                                                  │
│  ┌──────────┐    ┌───────────────────────────┐  │
│  │ fosm-rails│    │  fosm-rails-coding-agent  │  │
│  │ lifecycles│◄──►│                           │  │
│  └──────────┘    │  ┌─────────┐ ┌──────────┐ │  │
│                  │  │MCP Tools│ │ACP Agent  │ │  │
│                  │  │(pull)   │ │(push)     │ │  │
│                  │  └────┬────┘ └─────┬─────┘ │  │
│                  └───────┼────────────┼───────┘  │
└──────────────────────────┼────────────┼──────────┘
                           │            │
                    ┌──────┴────────────┴───────┐
                    │   Claude Code / Codex /    │
                    │   Copilot / OpenCode       │
                    └───────────────────────────┘

An MCP server embedded as Rack middleware at /fosm-agent/mcp. Coding agents query it on demand via standard MCP tool calls. Built on fast-mcp.

An ACP agent (bin/fosm-coding-agent) that implements the Agent Client Protocol. When a session starts, it proactively pushes FOSM lifecycle context — state definitions, events, guards, recent transitions — so the coding agent starts with full situational awareness.

The most powerful developer tooling doesn't wait for agents to discover context through trial and error — it pushes the right context at the right time. When your coding agent opens a PR that touches an Invoice model, it should already know that Invoice has a lifecycle with states draft → sent → paid, a guard requiring line items before sending, and that the last three transitions were all pay events. MCP lets the agent pull when it needs to; ACP lets the application push when it knows the agent should care.

Inspired by the thinking in The future of coding agents is vertical integration.

Add to your Gemfile:

gem "fosm-rails-coding-agent"

# Optional: for FOSM lifecycle introspection
gem "fosm-rails"

Run:

bundle install

Auto-activates in development via its Railtie. No configuration needed for basic use.

Then generate the MCP config for your coding agent:

rails generate fosm:mcp_config

This creates .mcp.json in your Rails root. Start Claude Code from the same directory:

claude

For a complete walkthrough with fosm-rails, sample lifecycle, seed data, and test prompts, see the Testing Guide.

In config/environments/development.rb:

config.fosm_coding_agent.allow_remote_access   = false     # default: localhost only
config.fosm_coding_agent.sql_row_limit         = 50        # max rows from execute_sql
config.fosm_coding_agent.eval_timeout_ms       = 30_000    # project_eval timeout
config.fosm_coding_agent.log_tail_default      = 100       # default log lines
config.fosm_coding_agent.acp_enabled           = true      # enable ACP agent
config.fosm_coding_agent.acp_push_fosm_context = true      # push FOSM context on session start

The ACP agent runs as a subprocess over stdio:

fosm-coding-agent

Or point your ACP client at the binary:

{
  "agent": {
    "command": "bundle",
    "args": ["exec", "fosm-coding-agent"]
  }
}

Coding agents need runtime intelligence, not just static code analysis. A state machine definition in source code tells you the structure; runtime introspection tells you the situation.

FOSM (Finite Object State Machine) is a paradigm where business entities have explicit, enforced lifecycles — with guards that explain why they block, transitions that log who did what, and access controls that make autonomous agent actions safe and auditable. This gem is the bridge between FOSM's runtime observability and the coding agents that need it.

Read the FOSM paper: Implementing Human+AI Collaboration Using Finite Object State Machine

bundle install
bundle exec rake spec

FSL-1.1-Apache-2.0 (Functional Source License, Version 1.1, Apache 2.0 Future License). See LICENSE.