Agent State

Supersedes agents.md /

Agent State started as a Git repository for persisting agent memory and organizational context across sessions. It grew into a collection of integrations, skills, and knowledge, all as plain Python scripts and markdown files.

Pick what you need, set your API keys, and your agents talk to Jira, Sentry, Stripe, GitHub, and 60+ other services. No frameworks, no protocol negotiation.

Works with Claude Code, Devin, Cursor, Windsurf, Copilot, Antigravity, and any agent that can run Python scripts.

Build your own See more

Build Your Toolbox

Select integrations, skills, and tools. Download a ready-to-use repository.

Integrations

authentication

sso-cli

CLI tool for fetching authentication tokens from Keycloak/OIDC providers, designed for AI agents and developers. Test protected API endpoints, get bearer tokens for curl, authenticate CLI scripts against SSO, and automate token retrieval in CI/CD pipelines.

Loading collection...
0 selected

Why Agent State Exists

Agent State started at Mottu as a shared Git repository where agents could persist what they learned: developer profiles, system ownership, helper scripts. It solved the problem of agents starting from scratch every session.

As agents needed to talk to more services (Jira, Sentry, Slack, GitHub), we kept adding Python scripts that wrapped each API. The repo grew from a memory layer into a full integration layer. Skills and behavioral modes followed.

Meanwhile, MCP, A2A, and other agent protocols appeared with competing standards, breaking changes, and complex configurations. We already had a simpler answer: standalone scripts, one per vendor, authenticated with environment variables, versioned in Git. Just python jira_cli.py search --query "bug".

  • Plain scripts Each integration is a single Python file. Read it, modify it, replace it.
  • Versioned in Git Every change is a commit. Roll back, branch, diff.
  • Community-driven 100+ items maintained through pull requests.
  • No lock-in No framework, no runtime, no SDK. Move scripts anywhere.
  • Any agent If it can run python script.py, it works.

How It Works

Each script is a self-contained CLI

Every integration follows the same pattern: a single Python file with argparse commands, environment variables for authentication, and JSON output. Agents call them like any CLI tool. 

# List your Sentry issues
python scripts/integrations/sentry/sentry_cli.py list-issues --status unresolved

# Create a Jira ticket
python scripts/integrations/jira/jira_cli.py create --project MYPROJ --summary "Fix auth bug"

# Check GitHub Actions status
python scripts/integrations/github-actions/github_actions_cli.py list-runs --repo my-org/my-repo

You own the repo

Agent State lives in your Git repository. Fork the template or build your own from the assembler above. Your agents get read/write access to this repo, and they use it to store scripts, organizational knowledge, and session context.

Environment variables, not config files

Each integration declares the API keys it needs. Set them in your .env file or your agent platform's secrets. For Keycloak/OIDC environments, sso-cli fetches auth tokens on demand from the system keyring.

What's Inside

  • Integrations (64) Jira, GitHub, Sentry, Stripe, Slack, Datadog, Notion, Supabase, and 56 more. Each is a CLI tool that wraps one vendor API.
  • Skills (28) Curated procedural knowledge from the agents.sh ecosystem. API design principles, debugging strategies, testing patterns, code review workflows.
  • Modes (3) Behavioral profiles that change how agents operate. Analyst mode, deployment guardrails, resource limit enforcement.
  • Orchestration (2) Multi-agent coordination. Session spawning, multi-layer handoff patterns.
  • Knowledge (4) Templates for organizational memory: developer profiles, system ownership, glossary, domain context.
  • Meta (1) Tools for the repo itself. Semantic search across your agent state.

Born in Production

Agent State emerged inside Mottu while scaling AI agents across thousands of repositories. These are from our actual use, not hypotheticals:

Reusable integrations

When an agent needed Jira access, it wrote a Python helper. That helper now lives in Agent State and is reused across every session, every agent, without regeneration. Scripts accumulate — agents get better over time.

Organizational memory

Agents store who owns which system, which PM manages which project, and each developer's GitHub username. New sessions start with this context instead of asking. This also enables agents to properly label PRs and identify the right stakeholders automatically.

Self-management

Agents use the orchestration scripts to spawn sub-sessions and manage their own resource limits. When approaching context or ACU limits, they create a new session with a summary and continue without human intervention.

A Different Approach

MCP (Model Context Protocol), A2A, and similar standards aim to create universal agent-to-service communication protocols. They are ambitious and important projects. Agent State takes a deliberately simpler approach.

Instead of a protocol with capability negotiation, server processes, and SDK dependencies, Agent State provides standalone Python scripts. Each script wraps exactly one vendor API, authenticates via environment variables, and outputs JSON. There is no runtime to install, no server to keep running, no protocol version to track.

Agent State is not a replacement for agent protocols in all cases. If you need real-time bidirectional communication between agents and services, a protocol may serve you better. But for the common case, an agent that needs to read Jira tickets, check Sentry errors, or post to Slack — a script is simpler, faster, and easier to debug.

Considerations

Script security

Scripts run with the agent's full permissions. Review them like code — because they are code. Agent-authored scripts deserve the same scrutiny as human-authored code.

Context window pressure

A large repo can overwhelm agents. Keep it well-organized, use scoped AGENTS.md files per folder, and curate ruthlessly. Bigger is not always better.

Concurrent writes

Multiple agents writing simultaneously can cause merge conflicts. Use branches per agent or per session, or partition by team.

Getting Started

  1. Build your toolbox Use the assembler above to select integrations and skills, or fork the template repo.
  2. Set your API keys Run ./setup.sh or copy .env.example to .env and fill in your keys.
  3. Install dependencies pip install -r requirements.txt
  4. Tell your agent Add to your AGENTS.md or agent knowledge base: "You have access to the agentstate repository. Use scripts in scripts/integrations/ to interact with external services."
  5. That's it. No protocol servers to start. No capability negotiation. Your agent can now use the tools.

FAQ

How is this different from MCP?

MCP is a protocol for agent-to-service communication. Agent State is a collection of scripts. MCP requires a server process and protocol negotiation; Agent State requires python script.py. Both can coexist. You can use Agent State integrations alongside MCP connections.

What agents does this work with?

Any agent that can run Python scripts and access a Git repository. Tested with Claude Code, Devin, Cursor, Windsurf, Copilot, and Antigravity.

Do I need to use all 100+ tools?

No. Use the assembler to pick only what you need. The resulting repo contains only your selected tools with auto-generated AGENTS.md files for navigation.

Can I add my own integrations?

Yes. The fastest way is to run the scaffold script and submit a PR: 

# Clone the collection
git clone https://github.com/caetanominuzzo/agentstate-awesome.git
cd agentstate-awesome

# Scaffold a new item (interactive)
./scripts/new-item.sh

# Implement your commands, then validate
python scripts/validate-item.py items/integrations/your-item/

# Open a PR

Or just suggest an item and someone else will build it. See the contributing guide for details.

What about persistent state and memory?

Agent State repositories also serve as persistent memory for your agents. The knowledge/ and memory/ directories store organizational context, developer profiles, and domain information that agents accumulate over time. This is complementary to the integration scripts.

Is this production-ready?

Agent State has been used in production at Mottu across thousands of repositories. The integration scripts are community-reviewed and follow consistent patterns. Review scripts before deploying — they run with your agent's permissions.