normsync check agent1 attack safe_zone   # Fails if "attack in safe_zone" is prohibited

flowchart LR
    A[Define WorldNorm\nname · condition · prohibited] --> B[NormStore\nSQLite backend]
    B --> C[NormMonitor\nloads active norms]
    C --> D[AgentAction\nagent_id · action · location]
    D --> E{Condition matches\nprohibited matches?}
    E -->|Yes| F[NormViolation\nstored + emitted]
    E -->|No| G[Action allowed]
    F --> H[Report\nJSON · Markdown · Rich table]

pip install normsync

from normsync import NormMonitor, WorldNorm, AgentAction, print_violations

# Define world norms
monitor = NormMonitor()
monitor.add_norm(WorldNorm(
    name="no-attack-in-safe-zone",
    description="Attacking is prohibited in safe zones",
    condition="safe_zone",
    prohibited="attack",
))

# Check agent actions
action = AgentAction("hero", "attack", "safe_zone")
violations = monitor.check(action)

print_violations(violations)
# → Norm Violations table: hero | no-attack-in-safe-zone | ...

# Repeal a norm at runtime
monitor.repeal_norm(monitor.active_norms()[0].id)

from normsync import NormStore, NormMonitor, NormRevision, WorldNorm, AgentAction, print_violations
import time

# Persist norms to SQLite (single file, shareable between agents)
store = NormStore(".normsync/norms.db")
norm = WorldNorm(
    name="no-attack-in-safe-zone",
    description="Attacking is prohibited in safe zones",
    condition="safe_zone",
    prohibited="attack",
)
store.save_norm(norm)
store.save_revision(NormRevision(norm_id=norm.id, revision_type="add", timestamp=time.time()))

# Load active norms into monitor and check actions
monitor = NormMonitor(store.get_norms(active_only=True))
action = AgentAction("hero", "attack", "safe_zone")
violations = monitor.check(action)
for v in violations:
    store.save_violation(v)

print_violations(violations)
# → Norm Violations table: hero | no-attack-in-safe-zone | ...

store.close()

from normsync import NormStore, NormVersionStore, WorldNorm

store = NormStore(".normsync/norms.db")
version_store = NormVersionStore(store)

norm = WorldNorm(
    name="no-friendly-fire",
    description="Friendly fire is prohibited",
    condition="friendly",
    prohibited="attack",
)
store.save_norm(norm)
v1 = version_store.record_change(norm, changed_by="admin", reason="initial rule")

# Retrieve full version history
history = version_store.get_history("no-friendly-fire")
print(f"Version {history[0].version} by {history[0].changed_by}: {history[0].change_reason}")
store.close()

normsync [--db PATH] COMMAND [OPTIONS]

# Add a norm
normsync add no-attack "No attacking in safe zones" safe_zone attack

# Check an action
normsync check hero attack safe_zone

# Export violations as JSON
normsync violations --format json

# Check constitution status
normsync status

# .github/workflows/normsync.yml
name: normsync constitution check
on: [push, pull_request]

jobs:
  norm-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: sandeep-alluru/normsync@main
        with:
          db: .normsync/norms.db
          fail-on-violation: "true"

# Start the MCP server
python -m normsync.mcp_server

# In your Claude Code project's .claude/settings.json:
{
  "mcpServers": {
    "normsync": {
      "command": "python",
      "args": ["-m", "normsync.mcp_server"]
    }
  }
}

# Install with REST API dependencies
pip install 'normsync[api]'

# Start the REST server
uvicorn normsync.api:app --reload

# Pass to Codex CLI or any OpenAI-compatible agent
codex --tools tools/openai-tools.json "Check which agent actions violated the world constitution"

normsync/
├── src/
│   └── normsync/
│       ├── norm.py           # WorldNorm, AgentAction, NormViolation, NormRevision dataclasses
│       ├── monitor.py        # NormMonitor — token-based norm checking
│       ├── store.py          # NormStore — SQLite persistence
│       ├── report.py         # print_violations(), to_json(), to_markdown()
│       ├── cli.py            # Click CLI (add, check, violations, revisions, status)
│       ├── api.py            # FastAPI REST server
│       └── mcp_server.py     # MCP server
├── tests/
│   ├── test_norm.py          # WorldNorm, AgentAction, NormViolation, NormRevision tests
│   ├── test_monitor.py       # NormMonitor unit tests
│   ├── test_store.py         # NormStore SQLite tests
│   ├── test_report.py        # Report formatter tests
│   ├── test_cli_runner.py    # CLI integration tests
│   └── test_api.py           # FastAPI endpoint tests
├── examples/
│   └── demo.py               # Standalone demo script
├── docs/                     # MkDocs documentation
├── tools/
│   └── openai-tools.json     # OpenAI function-calling tool definitions
├── assets/
│   ├── hero.png              # README hero image
│   └── logo.png              # Project logo
├── action.yml                # GitHub Action
├── openapi.yaml              # OpenAPI 3.1 spec
├── pyproject.toml            # Package metadata + dependencies
└── CONTRIBUTING.md           # Contribution guide