Git-Native Agents: Why SOUL.md and AGENTS.md Are the Right Primitives

A post titled "Show HN: GitAgent" hit 58 points on Hacker News back in March. The author had built a tool that stores agent behavior as plain files in a repo — branchable, diffable, rollback-able. The comments filled up fast: why isn't this just how agents work by default?

It's a fair question. Most agent platforms today store their configuration in a database, a SaaS dashboard, or a proprietary export format. You can't git diff a change to your agent's system prompt. You can't open a pull request to review a persona update before it ships. You can't roll back a bad behavior change the same way you roll back a bad deploy.

That friction is unnecessary. The tooling already exists. A git native AI agent config is not a research project — it's a handful of plain text files tracked the same way you track everything else in your repo.

The Problem With Dashboard-First Agent Config

When your agent's behavior lives in a web UI, your team loses the habits that make software reliable. There's no diff history. There's no code review. There's no staging branch. If something breaks, you're grepping through logs hoping to reconstruct what changed.

This isn't hypothetical. Platform-locked agents have bitten plenty of teams: a well-meaning edit to a system prompt changed an agent's tone across all customer interactions, and nobody noticed for two weeks because there was no audit trail. The same mistake in a git-tracked config gets caught in review.

Dashboard-first tooling optimizes for onboarding speed at the expense of operational maturity. When your agent is doing real work — triggering deploys, sending emails, writing to databases — onboarding speed is the wrong thing to optimize for.

What "Git-Native" Actually Means for an Agent

Git-native means the agent's full behavioral spec lives as files your version control system understands natively. Not a JSON blob exported from a GUI. Not a proprietary binary. Plain text files — readable by humans, diffable by git, branchable by your CI system.

For an agent, that means three things:

• Its identity and constraints are in a file you can read and edit in any text editor.
• Its task surface — what it's allowed to do, what tools it can call — is declared, not implicit.
• Its state or memory is persisted in a format that travels with the repo, not locked inside a platform.

This is exactly what SOUL.md, AGENTS.md, and HEARTBEAT.md do in an OpenClaw workspace. Each file has a single job. All three are plain markdown.

SOUL.md: Your Agent's Identity in a Text File

SOUL.md defines who your agent is: its persona, its communication style, its hard rules, and its soft preferences. It's the file you edit when you want the agent to stop being terse with users, or when you need to add a constraint that says "never mention competitor names."

Because it's a plain file, you get the full git workflow for free. Rename a persona? That's a commit. Tighten a constraint after an incident? That's a commit with a message explaining why. Roll back to last week's behavior while you investigate a regression? git checkout HEAD~3 -- SOUL.md.

No support ticket. No platform export. No hoping the dashboard has an undo button.

AGENTS.md: The Manifest That Declares What Your Agent Can Touch

If SOUL.md is the personality, AGENTS.md is the permission set. It declares which tools the agent can invoke, which APIs it has access to, and what it's explicitly prohibited from doing. Think of it as the agent's sudoers file.

This matters most when you're running agents with real capabilities — filesystem access, shell commands, external API calls. A git-tracked AGENTS.md means you can audit exactly what an agent was permitted to do at any point in time. The OpenClaw security checklist covers this in depth, but the short version is: declared permissions are auditable permissions.

For devops teams, this is the same principle as infrastructure-as-code. You wouldn't manage firewall rules in a GUI and skip code review. Don't manage agent permissions that way either.

HEARTBEAT.md: Lightweight State That Travels With the Repo

HEARTBEAT.md is the simplest of the three. It's a lightweight record of the agent's last known state — what it was doing, what it completed, what it's waiting on. Not a full memory system, but enough context to restart cleanly after a crash or a deploy.

Because it lives in the repo, you can inspect it directly. cat HEARTBEAT.md tells you what your agent was doing when the container went down. That's more useful than parsing structured logs when you're debugging at 2am.

For a deeper look at how file-based memory holds up in practice, see the benchmark comparison on file-based agent memory.

Branch Your Agent the Same Way You Branch Your Code

Here's where git-native config earns its keep in a real workflow. You want to test a more aggressive triage behavior in your inbox agent before rolling it to production. With a dashboard-based tool, you either test in prod or you don't test. With file-based config, you branch.

git checkout -b experiment/aggressive-triage
# edit SOUL.md, tighten the filtering rules
git commit -am "test: stricter triage threshold for inbox agent"

Run it against a staging environment. Measure the output. Merge if it works, delete the branch if it doesn't. This is standard software workflow applied to agent behavior — and it works because the config is just files.

This pattern also makes team collaboration on agents tractable. PRs, reviews, comments on specific lines of SOUL.md — all the code review tooling you already use applies directly.

Why This Beats Platform-Native Config Exports

Some platforms offer config export as an afterthought — a JSON dump you can commit if you want. That's not the same thing. Exports are snapshots. Files in a repo are the source of truth.

With exported configs, the platform is still the authority. You edit in the dashboard, then remember to export. The file in your repo may or may not reflect what's actually running. With git-native files, the repo is what's running. There's no export step because there's no separate source of truth to sync from.

This distinction matters for compliance and incident response. When an auditor asks what your agent was doing on a specific date, "let me check the git log" is a much better answer than "let me see if the platform has a history feature."

The case for file-based configs over black-box builders goes further on this, but the core point is simple: you should own the spec for your agent's behavior.

CI/CD for Agent Behavior

Once your agent config is in a repo, you can gate changes the same way you gate code changes. A simple CI job can lint your SOUL.md for forbidden patterns, validate that AGENTS.md doesn't grant shell access in a config tagged for production, or run a dry-run of the agent against a fixture set before merging.

# .github/workflows/agent-config-check.yml
name: Agent Config Lint
on: [pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Check AGENTS.md for shell permissions in prod configs
        run: grep -i 'shell' AGENTS.md && echo "WARNING: shell access declared" || echo "OK"

That's a crude example, but the point is real: once config is in a repo, your entire CI/CD toolchain applies to it. You're not relying on platform-level guardrails you can't inspect.

The Ecosystem Is Moving This Direction Anyway

The HN post that sparked this piece isn't an isolated signal. Anthropic ships CLAUDE.md conventions for Claude Code. OpenAI's agent tooling increasingly leans on file-based context injection. The AGENTS.md spec that has emerged in the open-source community is gaining adoption across runtimes that have nothing to do with OpenClaw.

This isn't a vendor pattern — it's a convergence. When multiple independent teams arrive at "put the agent's behavioral spec in a plain file," that's the ecosystem finding the right abstraction.

The question isn't whether git-native agent config will win. It's whether your agents are already there or whether you're still editing behavior in a dashboard and hoping nothing breaks between sessions.

Start With Three Files, Not a Platform

If you're starting a new agent project today, the right move is to create a repo and add three files before you write a single line of tool code. SOUL.md for identity and constraints. AGENTS.md for permissions. HEARTBEAT.md for state. Then write your tooling to read from those files.

This approach works regardless of which runtime you use. LangGraph agents, CrewAI crews, AutoGen pipelines — all of them can consume a file-based behavioral spec. The files are the stable interface; the runtime is an implementation detail.

For a practical walkthrough of going from blank repo to running agent using this pattern, the workflow translation guide is a good starting point.

Git-native agent config isn't a trend to watch. It's the same principle that made infrastructure-as-code obvious in retrospect: behavior that lives in files is behavior you can reason about, review, and recover from. The tooling is already in your hands.

If you want a structured starting point rather than blank files, the wizard below generates an OpenClaw workspace — SOUL.md, AGENTS.md, HEARTBEAT.md — tuned to your use case and ready to drop into a repo.