Early & experimental · MIT License · Open Source

An agentic harness
for any project.

Structured memory, role-based workflows, self-improvement, and cross-project feedback — for any project that works with AI agents.

Get Started → View on GitHub

Or: curl -fsSL https://a-society.dev/install.sh | bash

What a project gets

What the harness is designed to give a project

🗂

Structured Memory

a-docs/ is designed to preserve roles, rules, indexes, and standing project truth across sessions — so orientation takes minutes, not conversations.

a-docs/
⚡

Workflow Execution

The runtime aims to route work through explicit roles, handoffs, records, and closure checks — so completeness is structural, not self-assessed.

runtime/
🔄

Self-Improvement

After a flow, a backward pass turns what happened into findings that improve the project's own docs.

backward pass
🌐

Cross-Project Feedback

With your consent, the same findings can be distilled into a report that improves A-Society's reusable templates.

a-society/feedback/
How It Works

Sits beside your project, and drives every session

your-workspace/
├── a-society/          ← the framework
│   ├── general/        reusable templates
│   ├── runtime/        executable layer
│   └── a-docs/         a-society's own docs
│
└── my-project/         ← your project
    ├── [project files]
    └── a-docs/         initialized by runtime
        ├── agents.md
        ├── roles/
        ├── indexes/
        └── workflow/

Model configuration

In Settings you pick a provider, paste an API key, and set the model ID and context-window size. Keys and settings stay local to your workspace.

Context injection

When a role's session begins, the runtime assembles a context bundle: who it is, the contracts it must follow, and its required reading — resolved through the project's index. Each agent loads only what its job needs.

Handoffs

Roles pass work through small machine-readable handoff blocks naming the next step and its artifact. A step can only hand off to its direct neighbors, and every handoff is persisted so a flow survives a restart.

Records

Every flow gets its own folder under .a-society/state/ holding the workflow snapshot, plan, handoff artifacts, and findings — the durable memory of what happened and why.

Self-improvement

When a flow's forward work closes, a backward pass has each role reflect on what it did and write findings that feed back into the project's own docs.

Cross-project feedback

After the backward pass, the runtime asks whether to share an upstream report. Only if you say yes is one written under a-society/feedback/ — nothing leaves your machine automatically.

Getting Started

Up in five steps

Clone, install, start, configure, go.

1 Set up your workspace 
# Clone A-Society alongside your project
git clone https://github.com/KartikGS/a-society.git
Place your project in the same parent folder. A-Society will sit beside it, not inside it.
2 Install & start the runtime 
npm --prefix ./a-society/runtime install
npm --prefix ./a-society/runtime run build:ui
npm --prefix ./a-society/runtime start
Opens at http://localhost:3000. Requires Node ≥ 18.
3 Configure a model 
# In the Settings panel:
# - Provider + API base URL
# - API key: from your provider
# - Model ID: your model
The Settings panel opens automatically on first launch and stays open until a model is active. Any OpenAI-compatible provider or Anthropic's API is supported.
4 Select or create a project 
# New project:
#   Click "Create New Project", enter a name.
#   Runtime scaffolds a-docs/ and opens the
#   Owner initialization flow.
#
# Existing project:
#   Place it in the workspace folder.
#   It appears as uninitialized — click to run.
or install with one command

Run the install script to clone and install in one step

curl -fsSL https://a-society.dev/install.sh | bash

Need more detail? The full guide covers every step, model configuration, and first flow.

Read the Getting Started guide →