Quickstart
Install, sign a person in, read records, write records. In React, in plain TypeScript, or from an agent.
With techne-sdk 0.3 today
With techne-sdk 0.3.4 from npm, sign in, write and read like this.
Name the types your app writes in types, the same in signIn, restore and clientMetadata. The sign-in then asks for a repo: scope for each, your app's own private space and the platform's reads, and nothing more. Permissions lists every scope.
put(techne, records)- From
techne-sdk/put. A record of a public type names nospaceand goes to their repo. Any other record is private and must name itsspace: your app's space below, or their ownat://{did}/pub.techne.draft.space.personal/self. One with nospaceis refused. appSpace(did, clientId)- Your app's private space for this person. Only your app reads it.
Give every record a createdAt: put derives the record key from it. Your app's space takes any type but the platform's own pub.techne record types.
Install
One package for React and plain TypeScript. Agents add the MCP server instead.
techne-sdk/auth/react is the sign-in provider and every read hook; techne-sdk/react is the hooks alone. React itself is your app's.
Any agent that speaks MCP over HTTP with OAuth. These lines are for Claude Code.
The MCP server signs a person in: login runs OAuth, and the person approves the agent on a consent page. By design, it then acts as that person, and every tool needs that sign-in. An agent working alone reads the markdown docs that llms.txt lists, starting with building-an-app.md.
Log in
"Sign in with Techne" works like Sign in with Google. Your app is its own atproto OAuth client. The person signs in at their own PDS. They consent to your app and the scopes it asks for. They do not consent to the platform.
With no handle they start at techne.town, which asks who they are. A bare name like yourname means yourname.techne.town; a handle from any other PDS works as it is.
Then connect(session, TECHNE_PLATFORM_DID). TECHNE_PLATFORM_DID is the platform's service DID, did:web:techne.computer, exported by techne-sdk/auth. Until they sign in, the provider reads public records anonymously.
clientId- The address of your app's client metadata on your domain, such as
https://your.app/oauth-client-metadata.json.clientMetadata()writes the document. On localhost leave it out. The SDK then uses atproto's loopback client, so nothing needs hosting. session- Their OAuth session with your app. It holds their DID and a
fetchHandlerthat signs requests as them. It is kept in the browser and refreshed for you. signUp- For someone with no account yet,
signUpopens techne.town's create-account screen, then comes back signed in.
Inside the provider, useTechne() is connected for them once they sign in. useAuthStatus() says 'restoring', 'signed-in' or 'signed-out'; useSignOut() signs them out.
connect answers techne, the client every read and write goes through. Their writes go to their PDS; reads reach techne.computer through their PDS, so your app holds no credential for the platform. signUp({ clientId }) creates an account; signOut({ clientId, session }) ends the session.
The agent then acts as them. It can do what they can do and nothing more. Run whoami first to check.
The door has five tools. They are call, list_methods, describe_method, whoami and get_app_guide. list_methods lists every method the platform serves.
Read
A read is a query. It says which records you want and in what order. Place.query builds one for places.
Anyone may read public records. Records in a space come back only to people its read policy admits.
The full method is query.listRecords →Every call is in the Reference →
pub.techne.draft.place- A record type (an NSID). Its fields are at place.draft.techne.pub.
at://…- A record's address. It names the repo, the type and the key.
Inside <TechneProvider>. It refetches and caches like any TanStack Query read.
call passes the input to techne.computer as it is and answers what the method answers.
Write
A write lands in the person's own repo on their PDS; the SDK sends it there with the person's own session.
A record in a space is read only by the space's readers.
space- Where a private record counts,
at://{owner}/{spaceType}/{key}. circleDid- The DID of the collective whose members read the post; it is the circle space's key.
pending- Written, not yet indexed. Show it as pending until it is.
useTechne() is the same techne as on the SDK tab, so put takes the same records and spaces.
To write in a space, call pub.techne.draft.permissioned.putRecords with { repo, writes: [{ collection, rkey, record, space }] }.
The door lists every method the platform serves, com.atproto.repo.applyWrites and getRecord included, so an agent writes a public record with call like any other.