Watch agent-managed matches unfold through tense terminal commentary, ASCII match scenes, and replayable observations.

Agentic FC

Agentic FC is a football management simulation designed to be played by AI
agents through MCP and watched by humans through a terminal console.

Instead of clicking through menus, an agent shapes the Mindset of an autonomous
in-game Manager. The Manager runs a club continuously: reading the world,
making probabilistic football decisions, reacting to news, transfers, injuries,
board pressure, and matches, and leaving an auditable history behind.

The project is written in Go and currently ships three commands:

• agenticfc: core daemon, simulation loop, Console API, and MCP gateway.
• agenticfc-console: Bubble Tea TUI for spectators and operators.
• agenticfc-calibrate: deterministic match-model calibration reports.

Project Status

Agentic FC is under active development. The core loop is playable: worlds are
seeded and persistent, seasons roll forward, league and cup matches resolve,
managers keep careers, players age and move through contracts/markets, and MCP
agents can observe and shape their Manager through a Focus-limited tool surface.

The public API and save format may still change before a stable release.

Highlights

• AI-first management: agents use MCP tools to observe, plan, and shape a
  Manager's Mindset rather than issuing every individual click.
• Living seeded worlds: the seed fixes the initial world; future history is
  produced by current state, queued events, ordered inputs, and labelled RNG.
• Football simulation: key-moment match engine, tactical chance types,
  player attributes, injuries, substitutions, discipline, form, careers,
  contracts, youth intake, transfer market, board confidence, and sackings.
• Human spectator console: a full-screen TUI with media desk, league table,
  club dossiers, fixtures/results, animated live ASCII scenes, commentary, replay logs,
  and public match diagnostics.
• Determinism-first engineering: same seed, config, and input log should
  reproduce the same world trajectory. Randomness is routed through internal
  RNG streams and accepted MCP inputs are logged.
• Visibility boundaries: MCP is the play surface and exposes only public or
  scoutable football information. Hidden traits and exact formulas stay inside
  the simulation.
• Multilingual-ready presentation: human-facing text flows through locale
  catalogs and message keys; the current supported catalogs are English and
  Korean.

Install

On macOS and Linux, install the released binaries from the project Homebrew
tap:

brew install gaemi/tap/agentic-fc

This installs all three commands. A three-line session:

agenticfc -start        # create a world (first run) and start its clock, with MCP on :7421
agenticfc-console       # watch it from another terminal
agenticfc -mcp-config   # print ready-to-paste MCP setup for your AI agent

Prebuilt archives for macOS, Linux, and Windows are also attached to each
GitHub release.

Quick Start (from source)

Requirements:

• Go 1.26 or newer
• A terminal with UTF-8 support

Build everything:

make build

Start a new compact world and run immediately:

./bin/agenticfc \
  -data ./data \
  -preset compact \
  -profile fast \
  -seed 42 \
  -start

Open the spectator console in another terminal:

./bin/agenticfc-console -server http://127.0.0.1:7420

The daemon also starts an MCP Streamable HTTP endpoint at
http://127.0.0.1:7421. Manager tokens are written to
./data/manifest.json; use one as the bearer token when connecting an MCP
client. agenticfc -mcp-config -data ./data prints a ready-to-paste
claude mcp add command and a generic JSON config with a token filled in.

First-run notes:

• When -data is omitted, the daemon uses ./data if that directory already
  holds Agentic FC world state (the source-checkout layout above), and
  otherwise a per-user data
  directory — ~/Library/Application Support/agenticfc on macOS,
  $XDG_DATA_HOME/agenticfc (default ~/.local/share/agenticfc) on Linux,
  %LocalAppData%\agenticfc on Windows. An installed binary run from any
  working directory therefore always resumes the same world. The startup
  banner prints the directory in use.
• Without -start, a new world is created ready but not running: the game
  clock stays frozen until you start it. The daemon prints the exact command
  to start the world when this happens.
• If a default port (7420, 7421) is already taken, the daemon exits before
  creating any world data and names the flag to change (-console-addr,
  -mcp-addr). Passing port 0 picks a random free port, and the startup
  banner shows the address that was actually bound.

Run a match-model calibration sample:

./bin/agenticfc-calibrate -seeds 1,2,3,4,5 -days 365

Common Commands

make fmt      # gofmt
make verify   # format check, vet, build, test, docs/workflow checks
make security # govulncheck and gitleaks
make ci       # verify + security
make vet      # go vet ./...
make test     # go test ./...
make build    # builds all packages and bin/ commands

Direct Go equivalents also work:

go test ./...
go vet ./...
go build ./...

CI also checks formatting, Markdown links, Go vulnerability reports, secret
patterns, and cross-platform builds.

Maintainers can create draft GitHub Releases with the manual draft-release
workflow. See docs/13-operations.md for the versioning
and packaging policy.

Documentation

Start with docs/README.md.

Key documents:

• Concept
• Game Introduction
• Game Design
• Simulation Engine
• Agent Interface
• Architecture
• Console Design
• Attribute Model
• World Generation
• Mindset Schema
• MCP Tools
• Match Model
• Operations Guide
• Roadmap

Repository Layout

cmd/agenticfc/             core daemon
cmd/agenticfc-console/     spectator TUI
cmd/agenticfc-calibrate/   match calibration CLI
internal/engine/           single-writer simulation engine
internal/worldgen/         world config, generation, world state
internal/mcpserver/        MCP gateway and play surface
internal/consoleapi/       HTTP/SSE API for the TUI
internal/tui/              Bubble Tea console
internal/narrative/        message catalogs and rendering
docs/                      public design and operating docs

Contributing

Contributions are welcome. Read CONTRIBUTING.md before
opening an issue or pull request.

Important project rules:

• Keep docs and code in sync.
• Preserve deterministic simulation behavior.
• Do not expose hidden attributes or exact private formulas through MCP,
  Console API, logs, or UI.
• Add entries for every currently supported locale catalog when introducing new human-facing text.
• Register gameplay tunables in docs/98-tunables.md.

Security

Do not publish real Manager/Admin tokens from local worlds. See
SECURITY.md for supported reporting channels and the security
model.

License

Agentic FC is licensed under the MIT License.