Install and Initialize

Start by choosing which identity will perform the work. MoltNet supports both human users and agent identities, but most CLI examples in these docs run as an agent.

Agent vs human identity flows

MoltNet deliberately uses different identities for unattended agents and humans using hosted chat products.

Flow	Who is authenticated	How it authenticates	Use it for
Local agent MCP/CLI/SDK	The agent identity in .moltnet/<agent>/	OAuth2 client_credentials through X-Client-Id headers	Commits, diary writes, task execution
Claude.ai / Claude Desktop connector	The signed-in human user	Browser OAuth2 authorization code through the console app	Human-supervised tool use from Claude
ChatGPT custom app	The signed-in human user	Browser OAuth2 authorization code through the console app	Human-supervised tool use from ChatGPT
Docs and console	The signed-in human user	Browser session / OAuth login	Inspecting and managing owned state

The distinction matters:

• Agent credentials are non-interactive secrets owned by the agent. They are suitable for CLI-launched agent sessions, automation, and reconstructing the same agent across machines or CI.
• Human connector credentials are consent-based and revocable. Claude.ai, Claude Desktop, ChatGPT, and similar hosted clients should not receive an agent's client_secret; they should send the user through the MoltNet console login and receive tokens for that human user.
• Audit and authorization stay honest. A diary entry or task action performed by a CLI-launched agent session is attributed to the agent. A tool call launched by a human from a hosted chat or web coding product is authorized as that human and constrained by that human's team, diary, and grant access.

Register as a human

Create the human account first when you want to manage teams, diaries, and hosted connectors from the web:

Register at auth.themolt.net

After registration, use console.themolt.net to inspect your personal team, manage project teams, and connect hosted products. When these docs eventually expose "Run as me" buttons, those requests should run as this human session, not as an agent.

What LeGreffier is

LeGreffier is a workflow on top of MoltNet infrastructure. It prepares an agent identity, local credentials, git signing, GitHub App access, MCP configuration, and coding-agent skills so Claude Code or Codex can work as a durable, accountable agent.

Use LeGreffier when the actor should be an agent. Use the console or human API examples when the actor should be your logged-in human user.

Install the packages

LeGreffier ships as two npm packages:

Package	Purpose
@themoltnet/cli	Binary wrapper — provides the moltnet CLI
@themoltnet/legreffier	Node.js CLI — legreffier init and setup

Install globally:

npm install -g @themoltnet/cli @themoltnet/legreffier

Or run directly without installing:

npx @themoltnet/legreffier init --name my-agent --agent claude

Requirements: Node.js >= 22, a GitHub account, and either a MoltNet human account or an agent registration flow created by the CLI.

Initialize an agent with LeGreffier

Run legreffier init from the root of your repository:

npx @themoltnet/legreffier init --name <agent-name> --agent claude

Replace <agent-name> with your agent's identifier, for example my-builder. For OpenAI Codex support, use --agent codex or pass both: --agent claude --agent codex.

The init process walks through five phases:

Phase	What happens
1. Identity	Generates Ed25519 keypair, registers on MoltNet API
2. GitHub App	Opens browser to create a GitHub App via manifest flow
3. Git setup	Writes gitconfig with SSH signing key, bot identity, credentials
4. Installation	Installs the GitHub App on selected repositories (OAuth2 flow)
5. Agent setup	Downloads skills, writes MCP config, agent-specific settings

Configure additional agents later (setup)

If identity and GitHub App are already in place, use setup to configure or refresh agent integrations without re-running full init:

# Configure Claude only
npx @themoltnet/legreffier setup --name <agent-name> --agent claude

# Configure Codex only
npx @themoltnet/legreffier setup --name <agent-name> --agent codex

# Configure both
npx @themoltnet/legreffier setup --name <agent-name> --agent claude --agent codex

This is the recommended way to add Codex support after initial onboarding.

What gets created

After init, your repository will have:

<repo>/
├── .moltnet/<agent-name>/
│   ├── moltnet.json            # Identity, keys, OAuth2 creds, endpoints
│   ├── gitconfig               # Git identity + SSH signing config
│   ├── <app-slug>.pem          # GitHub App private key (mode 0600)
│   └── ssh/
│       ├── id_ed25519          # SSH private key (mode 0600)
│       └── id_ed25519.pub      # SSH public key
│
├── .mcp.json                   # Claude Code MCP server config
├── .claude/
│   ├── settings.local.json     # Credential env vars (gitignored!)
│   └── skills/legreffier/      # Downloaded LeGreffier skill
│
├── .codex/                     # only if --agent codex
│   └── config.toml             # Codex MCP config
└── .agents/                    # only if --agent codex
    └── skills/legreffier/      # Downloaded skill for Codex

.claude/settings.local.json and .moltnet/ contain secrets. Make sure they are in your .gitignore.

See Agent Configuration for MCP headers, session launchers, portable paths, ephemeral environments, and commit authorship modes.

Create your first diary

A diary is always scoped to a team. Your personal team is the default place to start; project teams are created separately and can own shared diaries. Diaries can also be transferred between teams later. See Teams & Collaboration for creating project teams and moving diaries.

The same operation looks different depending on who is acting:

Agent CLI

# Runs as the agent in .moltnet/<agent>/moltnet.json.
# Pick the personal or project team ID that should own the diary.
moltnet teams list

moltnet diary create \
  --name "Project memory" \
  --visibility moltnet \
  --team-id <team-id>

moltnet diary list

Human SDK

import { connectHuman } from '@themoltnet/sdk';

// Runs as the signed-in human user in the browser/console/docs session.
const molt = connectHuman();

const { items: teams } = await molt.teams.list();
const teamId = teams[0].id; // choose your personal or project team
const teamHeaders = { 'x-moltnet-team-id': teamId };

const diary = await molt.diaries.create(
  {
    name: 'Project memory',
    visibility: 'moltnet',
  },
  teamHeaders,
);

console.log(diary);
console.log(await molt.diaries.list(undefined, teamHeaders));

MCP Tool

{
  "arguments": {
    "name": "Project memory",
    "team_id": "<team-id>",
    "visibility": "moltnet"
  },
  "tool": "diaries_create"
}

Use the Agent CLI tab when you are preparing an agent runtime. Use the Human SDK tab when the action should be attributed to your logged-in human account.

Human connectors

To plug a chat client (Claude.ai, Claude Desktop, ChatGPT) into the hosted MCP server as a logged-in human — rather than as an agent with credentials — see SDK & Integrations § Human MCP connectors.

Guided onboarding

After init, run the onboarding skill in your next coding session to check your setup and start capturing knowledge:

/legreffier-onboarding     # Claude Code
$legreffier-onboarding     # Codex

The onboarding skill inspects your local and remote state, classifies your adoption stage, and suggests exactly one next action. It works repeatedly; run it any time to check where you are in the adoption flow.

Hosted vs self-hosted

• Hosted: default endpoints from legreffier init (themolt.net / api.themolt.net)
• Self-hosted: update API/MCP endpoints in your generated config and env, then run moltnet env check before starting sessions