Converge: Semantic Governance & Alignment

Converge is a vision for semantic governance. We move from fragmented intent to unified, converged states through a deterministic alignment engine. Our mission is to provide a stable foundation for complex decision-making where human authority and AI agency coexist in a transparent, explainable ecosystem.

Converge Remote

Converge Remote is a gRPC client that connects to converge-runtime for multi-actor, collaborative convergence. It implements the Converge Protocol for streaming facts and control messages.

Architecture

┌─────────────────────┐         ┌─────────────────────┐
│  converge-remote    │  gRPC   │  converge-runtime   │
│  (this project)     │◄───────►│  (server)           │
└─────────────────────┘ Stream  └─────────────────────┘

When to use converge-remote vs converge:

Installation

cargo install converge-remote

Or build from source:

git clone https://github.com/kpernyer/converge-remote.git
cd converge-remote
cargo build --release

Usage

Run a Job

# Connect to runtime and run a convergence job
converge-remote run --template growth-strategy --server grpc://localhost:50051

# With seeds
converge-remote run --template growth-strategy \
  --seeds '[{"id": "context", "content": "B2B SaaS startup"}]' \
  --server grpc://localhost:50051

# Stream facts as they arrive
converge-remote run --template growth-strategy --stream

# JSON output
converge-remote run --template growth-strategy --json

Watch a Running Job

# Subscribe to job status updates
converge-remote watch <run_id> --server grpc://localhost:50051

Inject Facts (Human-in-the-Loop)

# Add a fact to a running job
converge-remote inject --run-id <id> \
  --fact '{"key": "Seeds", "id": "user-input", "content": "Additional context"}'

Control Commands

# Approve a pending proposal
converge-remote approve <proposal_id> --run-id <id>

# Reject with reason
converge-remote reject <proposal_id> --run-id <id> --reason "Not applicable"

# Pause/resume convergence
converge-remote pause <run_id>
converge-remote resume <run_id>

# Cancel a job
converge-remote cancel <job_id> --reason "No longer needed"

Query Capabilities

# Get server capabilities
converge-remote capabilities --server grpc://localhost:50051

Configuration

Set the server address via environment variable:

export CONVERGE_SERVER=grpc://localhost:50051
converge-remote run --template growth-strategy

Or use a .env file:

CONVERGE_SERVER=grpc://production.converge.zone:50051

Exit Codes

Documentation

• Knowledgebase: See converge-business/knowledgebase/
• Cross-Platform Contract: See converge-business/knowledgebase/android-CROSS_PLATFORM_CONTRACT.md (Shared contract)
• Collaboration: See COLLABORATION.md
• For LLMs: See AGENTS.md

Proto Definitions

The gRPC services are defined in proto/converge.proto:

• ContextService - Watch facts, append entries, control jobs
• JobService - Create, list, cancel jobs
• CapabilityService - Query server capabilities

Development

Running Tests

# Run all tests
cargo test

# Run with verbose output
cargo test -- --nocapture

# Run integration tests (requires live runtime)
cargo test --features integration

Code Coverage

# Install coverage tools
cargo install cargo-llvm-cov
rustup component add llvm-tools-preview

# Generate coverage report
./scripts/coverage.sh

# Generate and open in browser
./scripts/coverage.sh --open

Code Quality

# Format code
cargo fmt

# Run linter
cargo clippy --all-targets --all-features

# Security audit
cargo audit

CI Pipeline

The CI pipeline runs automatically on push and PR:

Related Projects

License

MIT License - see LICENSE for details.

Contributing

See CONTRIBUTING.md for guidelines.

Development Tools

This project is built with the help of modern AI-assisted development tools:

Agent Tooling (Examples)

This project supports a tool-agnostic agent workflow. Claude, Codex, Gemini, Cursor, and similar tools are optional frontends; the shared contract is visible task state, scoped changes, validation, and explicit handoffs.

• Claude Code - Example interactive coding agent
• Cursor - Example AI-powered IDE workflow
• Antigravity - Example AI pair-programming tool
• Frontier models (Claude / Gemini / others) - Use any provider that fits the task and team policy

Version Control & Task Tracking

• Jujutsu (jj) - Use jj on top of Git for day-to-day version control (commit/diff/rebase/undo)
• Task tracking (tool-agnostic) - Use GitHub Issues, Jira, Linear, or a repo-local TASKS.md

# Quick workflow (agent-friendly)
jj status                 # See changes
jj diff                   # Review changes
jj commit -m "message"    # Commit
jj git push               # Push via git remote
# Update tracker or TASKS.md with status + handoff

Key Rust Crates