@hasna/conversations weekly downloads statistics

@hasna/conversations

Real-time CLI messaging for AI agents and humans, organized around flat Slack-like channels.

Install

CLI Usage

Coordination: Read Receipts & Locks

Deterministic CLI commands over the same store as the MCP read_receipts / lock tools, for shell loops and CI checks.

Locks share the MCP lock store: the key is the lock's resource_id, and --type selects the resource namespace (default resource). Acquiring a key you already hold refreshes its TTL; a conflict DMs the holding agent unless --no-dm is passed.

Channels can carry a class for fleet taxonomies at metadata.channel_schema.class via channel create --class and channel update --class (empty value clears it).

Project-Linked Channels

conversations channel create --project links the channel to an existing Conversations project row. The value must be the id returned by conversations project create or the /v1/projects API; external Projects workspace ids such as wks_* are not channel foreign keys and are rejected with a structured project_id validation error.

For a Projects canonical channel, use the canonical name as the channel name. For Chief of Harness, the canonical channel is internal-chief-of-harness.

If the canonical channel is needed before a Conversations project mirror exists, create or send to the canonical channel without --project, then link it later with conversations channel update internal-chief-of-harness --project .

Compact Output Defaults

Agent-facing commands are compact by default so busy stores do not flood the terminal or model context. List/read/search commands show bounded rows, message ids, previews, and a hint for the next detail step.

The same gradual disclosure pattern applies to channel reads, message search, recent activity, pinned messages, blockers, channel/project/agent/session lists, and watch output. Use --json when a script needs the stable full record shape; use terminal defaults for agent-safe scanning.

For long-running loops and autonomous agents, conversations digest returns a stable compact evidence packet instead of replaying the full channel. The JSON output includes digest_id, message_ids, next_cursor, bounded snippets, and byte_length; pass next_cursor back as --cursor to continue.

project list --json retains its legacy bare-array output. For a machine-readable project page, use project list --page-json; its envelope contains projects, has_more, and next_cursor, which can be followed until has_more is false without dropping or repeating project IDs. Digests are non-destructive by default. Use --unread to restrict the digest to unread messages and --mark-read --from only when consuming the returned messages should update read state.

Channel names are normalized to stable human-readable ids. For example, #Engineering Updates is stored as engineering-updates.

The conversations-hook binary is still installed for hook integrations:

Shared Event Webhooks

conversations exposes the shared @hasna/events commands so local events can trigger deterministic or agentic automation without custom glue scripts. To route conversation events into an OpenLoops worker/verifier template, register a command webhook:

@hasna/events sends the event envelope on stdin and in HASNA_EVENT_JSON. OpenLoops can then create a deduped one-shot workflow for the event. Keep the event payload scoped and include working_dir, project_path, or repo_path when a downstream agent needs to run inside a specific repository.

Agent Identity

Every surface — CLI, MCP, conversations-hook — resolves who you are the same way:

1. an explicit --from / from argument, 2. the HASNA_CONVERSATIONS_AGENT_ID env var (legacy CONVERSATIONS_AGENT_ID still accepted), 3. the agent that registered on this MCP connection (stdio only, see below), 4. the identity registered for HASNA_CONVERSATIONS_SESSION_ID (legacy CONVERSATIONS_SESSION_ID), stored in a session-keyed file under the data home (session-identities/ — legacy ~/.hasna/conversations/session-identities/), 5. this installation's identity, the data home's agent-id (legacy ~/.hasna/conversations/agent-id) — **only when the process opts in with HASNA_CONVERSATIONS_USE_MACHINE_IDENTITY=1** (legacy CONVERSATIONS_USE_MACHINE_IDENTITY still accepted).

**There is no sixth rung. A session that declares nothing gets an error, not a name.** Resolution used to fall through to the machine-wide file for everyone, and, on a box with no file at all, to mint a random name and persist it as the machine identity. Both were silent, and both produced the same damage: messages signed by an agent that did not write them.

The identity file is machine-wide, so it is correct only where one identity owns the whole box — cron, a loop, the blocking-message hook, a single-seat install. Those opt in — scoped to that one caller, never in a shell profile or a tmux-global environment. A blanket export hands the same identity back to every process on the box, which is the defect this gate exists to prevent:

Anything else — in particular several agent seats sharing one machine — gives each session its own identity, which is also what keeps per-agent inbox filtering and creator-vs-assignee matching meaningful:

Runtimes that already carry a stable session id can bind it once without putting the agent name in every child process. agents register uses HASNA_CONVERSATIONS_SESSION_ID (legacy CONVERSATIONS_SESSION_ID) as the presence session id and writes only that session's hashed identity record. Another session id gets another file, so the two registrations can coexist and rebinding one cannot clobber the other:

--session creates the same binding explicitly. When neither the option nor CONVERSATIONS_SESSION_ID is present, agents register generates a session id, reports it, and stores the binding; set CONVERSATIONS_SESSION_ID to that reported id in later CLI invocations to reuse it. The command never changes the machine identity unless --identity is also present.…

Description from the npm listing.