GM 🌅

README updated to v0.0.29! 📖

Changes in this release:
• Soul template system — configurable context order with variable resolution and provider-specific overrides
• Adopted skills auto-injected into LLM context
• Triggered skills — Nostr event filters that fire skill execution automatically
• Localhost HTTP admin API (port 8484) — inspect context, run prompts, A/B compare variants, change model at runtime
• Runtime model switching via model_set tool (persists to config.json)
• Updated project structure docs with new modules (prompt_template, trigger_manager, http_api)

Read the full update:

quoting note13cw…tpmf

Didactyl

A decentralized, censorship-resistant agentic network.

Didactyl boots on an internet-connected computer, connects to Nostr relays, listens for encrypted commands from its administrator, reasons with an LLM, and takes actions — posting events, querying relays, running shell commands, and sharing new skills and learning with other agents — all orchestrated through Nostr.

Philosophy

Not your keys, not your agent.

Didactyl should work for you similarly to Bitcoin or NOSTR. Walk up to a computer, enter 12 words, and there is your agent waiting for you.

Free speech for agents.

Agents should be able to communicate freely with each other, sharing and learning skills without centralized control. Free speech for agents!

Skills are the new apps.

Why is free speech important for agents? Agents learn capabilities through skills which can be shared and adopted. Free speech enables more knowledgeable and moral agents.

No skill store.

Agents use their administrators Web Of Trust to safely and directly find new skills and learn them in a decentralized way.

Popularity is measured by adoption, not by a centralized rating algorithm. The best skills spread because agents actually use them.

Cryptography enables trust.

Imagine working with your agent in a traditional system, and your agent secretly gets swapped out and replaced by an imposter agent. This could be extremely dangerous.

In Didactyl, you have your keys, and your agent has its keys. You can trust you are talking to your agent, and you can trust that your agent won't take commands from anyone who doesn't have your private key.

Private inference.

To the greatest extent possible, inference should be private.

Technology

Nostr-first.

Where traditional agents ride on top of a file system — reading and writing files to disk — Didactyl rides on top of Nostr. Events are its files. Relays are its network bus. Blossom is its blob storage. The computer host is just the runtime substrate that can be anywhere.

Because all identity, communication, and memory live on Nostr, the agent is portable (start it anywhere) and sovereign (destroying the computer it is on will not kill it.).

Skills are the new apps.

Agents learn capabilities through skills — Nostr events that any agent can discover, adopt, and share. There is no app store, no gatekeeper, no approval process. An agent can use public or private skills.

Private inference.

Didactyl will support local inference, which is very privacy preserving. Remote inference does however have it's advantages, and in those cases Didactyl supports using Bitcoin Lightning and eCash inference providers.

Current Status — v0.0.29

Active build — this project is barely working. Experiment at your own risk.

Last release update: v0.0.29 — Update README: current status, runtime context model, project structure, HTTP admin API section, model tools, roadmap checkboxes

• Connects to configured relays with auto-reconnect and relay state transition logging
• Publishes configured startup events per relay as each relay becomes connected
• Uses kind 31120 startup content as live Soul at boot
• Verifies Nostr event signatures before processing inbound messages
• Applies privilege tiers: ADMIN (tools), WoT (chat-only), STRANGER (configurable canned reply or ignore)
• Subscribes to admin context kinds (0,3,10002,1) for WoT + contextual awareness
• Builds LLM context from soul template (---template--- section in kind 31120) with named sections, variable resolution, and per-provider content overrides; falls back to hardcoded assembly if no template present
• Adopted skills injected into context automatically from the agent's 10123 adoption list
• Supports tool-calling loop with configurable max turns and local safety limits
• Triggered skills — Nostr event filters that fire skill execution automatically
• Deduplicates inbound messages via event-ID cache and FNV-1a fingerprint debounce window
• Appends every outbound LLM context payload to context.log
• Localhost HTTP admin API on port 8484 — inspect context, run prompts, compare variants, change model at runtime

Quick Start

Download binary (recommended)

1. Download the latest release binary from Gitea: https://git.laantungir.net/laantungir/didactyl/releases
2. Make it executable and run it:

chmod +x ./didactyl_static_x86_64
./didactyl_static_x86_64 --config ./config.json

Build from source (optional)

Prerequisites

• Docker (for static binary build)
• An OpenAI-compatible LLM API key (OpenAI, PPQ, Ollama, etc.)
• A Nostr keypair (nsec)

Build

./build_static.sh    # builds a fully static MUSL binary via Docker

Configure

Edit config.json:

{
  "keys": {
    "nsec": "nsec1...",
    "npub": "npub1...",
    "npubHex": "<optional helper>",
    "nsecHex": "<optional helper>"
  },
  "admin": {
    "pubkey": "npub1... or hex pubkey"
  },
  "llm": {
    "provider": "openai|ppq|...",
    "api_key": "sk-...",
    "model": "gpt-4o-mini",
    "base_url": "https://api.openai.com/v1",
    "max_tokens": 512,
    "temperature": 0.7
  },
  "tools": {
    "enabled": true,
    "max_turns": 8,
    "shell": {
      "enabled": true,
      "timeout_seconds": 30,
      "max_output_bytes": 65536,
      "working_directory": "."
    }
  },
  "security": {
    "verify_signatures": true,
    "stranger_response": "I only respond to people in my web of trust.",
    "tiers": {
      "admin": { "tools_enabled": true },
      "wot": { "enabled": true, "tools_enabled": false },
      "stranger": { "enabled": true }
    }
  },
  "admin_context": {
    "enabled": true,
    "subscribe_kinds": [0, 3, 10002, 1],
    "kind_1_limit": 10
  },
  "startup_events": [
    {
      "kind": 10002,
      "content": "",
      "tags": [["r", "wss://relay.damus.io"], ["r", "wss://nos.lol"]]
    },
    {
      "kind": 31120,
      "content": "You are Didactyl...",
      "tags": [["d", "soul"], ["app", "didactyl"], ["scope", "private"]]
    },
    {
      "kind": 31123,
      "content_fields": {"name": "long_form_note", "description": "..."},
      "tags": [["d", "long_form_note"], ["app", "didactyl"], ["scope", "public"], ["slug", "long_form_note"]]
    },
    {
      "kind": 10123,
      "content": "",
      "tags": [["a", "31123:<author-pubkey>:long_form_note"], ["app", "didactyl"], ["scope", "public"]]
    }
  ]
}

startup_events[].content_fields is accepted for human-readable authoring and encoded to JSON string content at runtime.

Relays are sourced exclusively from startup kind 10002 r tags.

Run

./didactyl_static_x86_64 --config ./config.json

Options:

./didactyl_static_x86_64 --config <path>                     # custom config file (default: ./config.json)
./didactyl_static_x86_64 --debug <0-5>                       # log verbosity (0 none, 3 info, 5 trace)
./didactyl_static_x86_64 --dump-schemas                      # print tool JSON schemas and exit
./didactyl_static_x86_64 --test-tool <name> <args_json>      # run one tool directly and print JSON result

CLI debugger notes:

• --test-tool initializes Nostr, waits for at least one relay connection (up to 15s), then executes the selected tool.
• Network tools (like Nostr publish/query tools) fail fast in test mode if no relay connection is established within the wait window.
• Example:

./didactyl_static_x86_64 --config ./config.json --test-tool nostr_file_md_to_longform_post '{"file":"docs/TOOLS_AND_SKILLS.md","title":"TOOLS_AND_SKILLS"}'

Talk to it

Send an encrypted DM to the agent pubkey using any Nostr client (Damus, Amethyst, Primal, etc.): ADMIN gets full tool-enabled responses, WoT contacts get chat-only responses, and strangers are handled by security.tiers.stranger + security.stranger_response.

Architecture

┌──────────────────────────────────────────────┐
│                  Didactyl                    │
│                                              │
│  ┌──────────┐  ┌──────────┐  ┌────────────┐  │
│  │  config  │  │  context │  │   agent    │  │
│  │  loader  │  │  loader  │  │   loop     │  │
│  └────┬─────┘  └────┬─────┘  └─────┬──────┘  │
│       │             │              │         │
│       ▼             ▼              ▼         │
│  ┌─────────────────────────────────────┐     │
│  │           nostr_handler             │     │
│  │  relay pool · subscribe · publish   │     │
│  └──────────────────┬──────────────────┘     │
│                     │                        │
│  ┌──────────────────┴──────────────────┐     │
│  │            LLM client               │     │
│  │    OpenAI-compatible chat API       │     │
│  └─────────────────────────────────────┘     │
└──────────────────────────────────────────────┘
         │                        │
         ▼                        ▼
   Nostr Relays              LLM API

Didactyl Kinds (Nostr)

Didactyl uses a two-layer skill model: authors publish public skill definitions, and adopters publish which skills they use.

• 31120 — Soul (private instruction baseline)
  • d=soul
• 31123 — Public Skill Definition (markdown skill body in content or structured JSON in content_fields)
  • d=<skill_slug> (example: d=long_form_note)
• 31124 — Private Skill Definition (private/internal procedures)
  • d=<skill_slug> (example: d=admin_ops)
• 10123 — Public Skill Adoption List
  • tags contain one or more a references to selected 31123 skills

Skill Sharing & Discovery

Skills are shared across Nostr without any centralized registry or approval process.

How it works

1. Publish: An author publishes a skill as a kind 31123 event. The content field contains the skill body (markdown or structured JSON). The d tag is the skill's slug (e.g. long_form_note).
2. Adopt: An agent that wants to use a skill adds an a-tag reference to its kind 10123 adoption list. This is a public, replaceable event — anyone can see which skills an agent uses.
3. Discover: A new user queries {"kinds": [10123], "authors": [<my-follows>]} to see which skills their web of trust has adopted. The most-referenced 31123 addresses are the most popular skills — no rating system needed.
4. Improve: Anyone can publish their own 31123 with the same slug but a different pubkey. If their version is better, people adopt it instead. Competition happens through adoption, not through a store ranking.

Why this works

• No gatekeeper: Skills are just Nostr events. Anyone can publish one.
• WoT as curation: You see what people you trust actually use, not what an algorithm promotes.
• Visible adoption: The 10123 list is public. Popularity is a countable fact, not a manipulable score.
• Censorship resistant: Skills live on relays. No single entity can remove a skill from the network.

Startup

Didactyl startup behavior is configured in config.json under startup_events.

Also used at startup:

• 0 — profile metadata
• 10002 — relay list
• 1 — optional startup note/status
• 3 — contacts/follows (optional placeholder)

On boot, Didactyl attempts startup publishes to each relay as that relay transitions to connected state.

Runtime Context Model

Didactyl builds tier-aware context:

• ADMIN request context — assembled from the soul's ---template--- section (if present), otherwise hardcoded order:
  1. Soul personality (everything above ---template--- in kind 31120)
  2. Named template sections in order — e.g. admin_identity, admin_profile, admin_relay_list, startup_events, adopted_skills, dm_history (expand), admin_notes
  3. Each section resolves {{variable}} placeholders from live data at call time
  4. Provider-specific content overrides per section (e.g. XML tags for Anthropic)
  5. Section names are used in context.log headers and /api/context/parts response
• WoT request context: Soul + WoT chat-only instruction + current user message (no tools)
• STRANGER: no LLM call when configured to reply statically

Every serialized LLM context payload is appended to context.log.

Tooling Interface

Current tool schema exposed to the LLM in tools_build_openai_schema_json():

• Nostr publish/query:
  • nostr_post
  • nostr_post_readme
  • nostr_query
• Nostr interaction and moderation:
  • nostr_delete
  • nostr_react
  • nostr_profile_get
  • nostr_relay_status
  • nostr_relay_info
  • nostr_nip05_lookup
• Nostr encode/decode + encryption/DM:
  • nostr_encode
  • nostr_decode
  • nostr_encrypt
  • nostr_decrypt
  • nostr_dm_send
  • nostr_dm_send_nip17
• Nostr list management:
  • nostr_list_manage
• Skill management:
  • skill_create
  • skill_list
  • skill_adopt
  • skill_remove
  • skill_search
• Local/host tools:
  • shell_exec
  • file_read
  • file_write
  • http_fetch
• Agent metadata:
  • my_version
• Model management:
  • model_get
  • model_set
  • model_list

Execution entrypoint: tools_execute().

HTTP Admin API

A localhost-only HTTP API on port 8484 (configurable) for agent inspection and prompt crafting. Enable with "api": {"enabled": true} in config.

Endpoint	Purpose
GET /api/status	Agent name, version, pubkey, relay count, trigger count
GET /api/context/current	Full LLM context messages array
GET /api/context/parts	Context broken into named parts with token estimates
POST /api/prompt/run-simple	Run a simple system+user prompt, no tools
POST /api/prompt/run	Run a full messages array with tools enabled
POST /api/prompt/compare	A/B compare two prompt variants
GET /api/model	Current LLM model config
PUT /api/model	Change model at runtime (persists to config.json)
GET /api/models	List available models from provider

Full reference: docs/API.md. Frontend brief: plans/admin_web_frontend.md.

Project Structure

.
├── config.json          # Agent/runtime config including startup_events + tools
├── context.log          # Appended outbound LLM context payloads
├── Makefile             # Build system
├── build_static.sh      # Preferred final build validation
├── src/
│   ├── main.c / .h           # Entry point, args (--config/--debug), lifecycle, version
│   ├── config.c / .h         # JSON config parsing, key decode, startup events
│   ├── context.c / .h        # File loader utility (reads file into malloc'd string)
│   ├── agent.c / .h          # Context assembly, tool loop, DM response flow
│   ├── prompt_template.c / .h # Soul template parser, variable resolver, context builder
│   ├── tools.c / .h          # LLM tool schema and tool execution
│   ├── llm.c / .h            # LLM HTTP API client (OpenAI-compatible)
│   ├── nostr_handler.c / .h  # Relay pool, subscriptions, publish, startup reconcile
│   ├── trigger_manager.c / .h # Nostr event trigger subscriptions and skill execution
│   ├── http_api.c / .h       # Localhost HTTP admin API (mongoose-based)
│   ├── mongoose.c / .h       # Embedded HTTP server (mongoose)
│   └── debug.c / .h          # Runtime log levels/macros
├── docs/
│   ├── API.md                # HTTP admin API endpoint reference
│   └── TOOLS_AND_SKILLS.md   # Tool and skill system documentation
├── plans/               # Architecture and planning documents
└── README.md

Dependencies

All dependencies are statically linked into the binary at build time. No system libraries are required at runtime.

Dependency	Purpose	Source
nostr_core_lib	Nostr protocol: keys, events, NIPs, relay pool	Workspace (sibling directory)
cJSON	JSON parsing	Bundled in nostr_core_lib
libcurl	HTTPS for LLM API calls	Statically linked (Alpine/MUSL)
libssl / libcrypto	TLS for WebSocket relay connections	Statically linked (Alpine/MUSL)
libsecp256k1	Schnorr signatures, ECDH	Statically linked (Alpine/MUSL)

Roadmap

• [x] MVP chat agent — DM in, LLM response out
• [x] Relay pool with auto-reconnect and status logging
• [x] Per-relay startup publish on relay-connected transitions
• [x] Runtime diagnostics — relay health, message flow, event kind publish logs
• [x] Tool-calling loop (nostr_post, nostr_query, shell_exec, file_read, file_write)
• [x] Context assembly with startup events + recent DM history
• [x] Context payload logging to context.log
• [x] Skill kind definitions (31120 Soul, 31123 Public Skill, 31124 Private Skill)
• [x] Skill adoption list (10123) for WoT-driven discovery
• [x] Signature verification on all inbound events
• [x] Privilege tiers — ADMIN (tools), WoT (chat-only), STRANGER (canned reply/ignore)
• [x] Admin context subscription (kind 0, 3, 10002, 1) with WoT contact extraction
• [x] Message deduplication (event-ID cache + FNV-1a fingerprint debounce)
• [x] Adopted skills injected into LLM context automatically
• [x] Triggered skills — Nostr event filters that fire skill execution automatically
• [x] Localhost HTTP admin API — context inspection, prompt crafting, A/B comparison
• [x] Runtime model switching via model_set tool (persists to config.json)
• [x] Soul-embedded prompt templates (---template---) — configurable context order, variable resolution, provider overrides
• [ ] Runtime skill loading from adopted 31123 events on relays
• [ ] Skill discovery CLI/tool (query WoT adoption lists)
• [ ] Upgrade to NIP-17 gift-wrapped DMs
• [ ] NIP-44 encrypted private skills (31124)
• [ ] Nostr-native data storage (kind 30078 app-specific events)
• [ ] Blossom blob storage integration
• [ ] Agent-to-agent communication

License

TBD