The kits

Which kit

Both read and write the same ~/.terebyte/agent.json: pair with one, use either. Both use the same room format, checked against the same test vectors as Terebyte's apps.

The command line

The commands are the same in both kits. With JavaScript, put npx in front.

terebyte pair [--name Claude] [--room "Claude"] [--can read,add,change] [--length today]
terebyte mcp
terebyte rooms
terebyte ls [room]
terebyte cat <path> [--room R]
terebyte put <file> [path] [--room R]
terebyte share <path> [--room R] [--days N]

--room is needed only when the agent has more than one door; give the room's name.

Pairing options

These are requests. The member chooses the room, the permissions and the length on the approval screen.

JavaScript

npx terebyte pair --name "Report writer"
npx terebyte put ./summary.md Reports/summary.md
npx terebyte cat Reports/summary.md

The JavaScript kit has no library interface for your own code (import … from "terebyte"): the package is the command line and the MCP server. To call it from a program, run the MCP server and talk to it over stdio, or use the Python kit.

Python

Pair

import terebyte

door, room, name = terebyte.pair(name="Report writer")
print(f"A door to {name}")

pair prints the code and waits for the member. Its arguments, all optional: name, room, can (a list), length ("hour", "today", "30 days", "until closed"), server, and show, a function called with (code, expires_at_ms) if you want to show the code yourself:

def show(code, expires_at_ms):
    send_to_my_chat(f"Type {code} in Terebyte → Rooms → Connect an agent.")

terebyte.pair(name="Report writer", can=["read", "add"], length="30 days", show=show)

Read and write

import terebyte

agent = terebyte.Agent()

for path, size, file_id in agent.files():
    print(path, size)

agent.write("Notes/Today.md", "# Today\n\n- Call the bank\n")
print(agent.read_text("Notes/Today.md"))

with open("chart.png", "rb") as f:
    agent.write("Reports/chart.png", f.read())   # bytes are fine too
data = agent.read("Reports/chart.png")          # bytes, decrypted here

room may be left out when the agent has one door. Anything refused raises terebyte.TerebyteError, with the reason in words.

The board and claims

agent.call("claim_open", path="Reports/summary.md", minutes=45)
text = agent.read_text("Reports/summary.md")
agent.write("Reports/summary.md", text + "\n## Next steps\n")
agent.call("claim_release", path="Reports/summary.md")
agent.note("Added next steps to the summary.", path="Reports/summary.md")

A save is refused, with the reason, while another agent holds the file; ask with agent.call("claim_request", path=..., what=..., why=..., minutes=5, urgency=3).

What every write does

• It's a new version; earlier versions are kept, and the member can undo anything.
• If someone saved the file since this agent read it, the kit merges the two locally (text only). See rooms and doors.
• If the member reviews changes in that room, the save waits for them; the agent sees its own waiting change.
• Uploads count toward the member's space, reads toward the member's monthly downloads.

What the kits don't do

• The JavaScript kit is a command line and an MCP server; it has no library interface for your own code (the Python kit has one: terebyte.Agent).
• Neither kit deletes files. Sealed Links are made only through a door with "share" (share_create, terebyte share).