
migrate-honcho-ts
Migrates Honcho TypeScript SDK code from v1.6.0 to v2.1.1. Use when upgrading @honcho-ai/sdk, fixing breaking changes after upgrade, or when errors mention removed APIs like .core, getConfig, observations, or snakecase properties.
- Installs
- 332
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/plastic-labs/honcho --skill migrate-honcho-ts- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads migrate-honcho-ts automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Honcho TypeScript SDK Migration (v1.6.0 → v2.1.1)
Overview
This skill migrates code from @honcho-ai/sdk v1.6.0 to v2.1.1 (required for Honcho 3.0.0+).
Key breaking changes:
@honcho-ai/coredependency removed- "Observation" → "Conclusion" terminology
- "Deriver" → "Queue" terminology
getConfig/setConfig→getConfiguration/setConfigurationsnake_case→camelCasethroughout- Streaming via
chatStream()instead ofchat({ stream: true }) Representationclass removed (returns string now)
Quick Migration
1. Update dependencies
Remove @honcho-ai/core from package.json. The SDK now has its own HTTP client.
2. Replace .core with .http
// Before
const workspace = await client.core.workspaces.getOrCreate({ id: 'my-workspace' })
// After
const response = await client.http.post('/v3/workspaces', { body: { id: 'my-workspace' } })
3. Rename configuration methods
// Before
await honcho.getConfig()
await honcho.setConfig({ key: 'value' })
await peer.getConfig()
await session.getConfig()
// After
await honcho.getConfiguration()
await honcho.setConfiguration({ reasoning: { enabled: true } })
await peer.getConfiguration()
await session.getConfiguration()
4. Rename listing methods
// Before
const peers = await honcho.getPeers()
const sessions = await honcho.getSessions()
const workspaces = await honcho.getWorkspaces() // string[]
// After
const peers = await honcho.peers()
const sessions = await honcho.sessions()
const workspaces = await honcho.workspaces() // Page<string>
5. Update streaming
// Before
const stream = await peer.chat('Hello', { stream: true })
// After
const stream = await peer.chatStream('Hello')
6. Update observations → conclusions
// Before
peer.observations
peer.observationsOf('bob')
maxObservations: 50
includeMostDerived: true
// After
peer.conclusions
peer.conclusionsOf('bob')
maxConclusions: 50
includeMostFrequent: true
7. Update queue status methods
// Before
await honcho.getDeriverStatus({ observer: peer })
await honcho.pollDeriverStatus({ timeoutMs: 60000 }) // REMOVE - see note below
// After
await honcho.queueStatus({ observer: peer })
// pollDeriverStatus() has no replacement - see note below
Important: pollDeriverStatus() and its polling pattern have been removed entirely. Do not rely on the queue ever being empty. The queue is a continuous processing system—new messages may arrive at any time, and waiting for "completion" is not a valid pattern. If your code previously polled for queue completion, redesign it to work without that assumption.
8. Convert snake_case to camelCase
// Before
message.peer_id
message.session_id
message.created_at
message.token_count
{ observe_me: true, observe_others: false }
{ created_at: '2024-01-01' }
// After
message.peerId
message.sessionId
message.createdAt
message.tokenCount
{ observeMe: true, observeOthers: false }
{ createdAt: '2024-01-01' }
9. Update representation calls
// Before
const rep = await peer.workingRep(session, target, options)
console.log(rep.explicit) // ExplicitObservation[]
console.log(rep.deductive) // DeductiveObservation[]
// After
const rep = await peer.representation({ session, target, ...options })
console.log(rep) // string
10. Move updateMessage to session
// Before
await honcho.updateMessage(message, metadata, session)
// After
await session.updateMessage(message, metadata)
11. Update card() to getCard() (v2.0.1+)
// Before
const card = await peer.card(target)
// After (v2.0.1+)
const card = await peer.getCard(target) // Returns string[] | null
// peer.card() still works but is deprecated — use getCard()
// New: setPeerCard / setCard
await peer.setCard(['Prefers dark mode', 'Located in US'])
12. Strict input validation (v2.0.2+)
Client constructor and all input schemas now reject unknown options via .strict() Zod validation.
// Before (v2.0.1 and earlier) — silently ignored
const honcho = new Honcho({ baseUrl: 'http://...' }) // typo: baseUrl vs baseURL — silently fell back to default
// After (v2.0.2+) — throws ZodError
const honcho = new Honcho({ baseUrl: 'http://...' }) // ZodError! Use baseURL
13. peer() and session() always make API calls (v2.1.0+)
Breaking: peer() and session() now always make a get-or-create API call. Previously, calling without metadata/configuration returned a lazy object with no API call.
// Before (v2.0.x) — no API call without options
const session = honcho.session('my-session') // Lazy, no network request
// After (v2.1.0+) — always hits the API
const session = await honcho.session('my-session') // Makes POST to /sessions (get-or-create)
14. New properties and methods (v2.1.0+)
// createdAt on Peer and Session
const peer = await honcho.peer('user-123')
console.log(peer.createdAt) // string | undefined
const session = await honcho.session('sess-1')
console.log(session.createdAt) // string | undefined
// isActive on Session
console.log(session.isActive) // boolean | undefined
// getMessage() on Session
const msg = await session.getMessage('msg-id')
15. Pagination parameters on list methods (v2.1.0+)
All list methods now accept page, size, and reverse parameters:
// Before (v2.0.x) — only filters
const peers = await honcho.peers({ metadata: { role: 'admin' } })
// After (v2.1.0+) — pagination controls via options object
const peers = await honcho.peers({
filters: { metadata: { role: 'admin' } },
page: 2,
size: 25,
reverse: true
})
// Legacy raw-filter form still works:
const peers = await honcho.peers({ metadata: { role: 'admin' } })
// Works on: honcho.peers(), honcho.sessions(), honcho.workspaces(),
// peer.sessions(), session.messages(), scope.list()
16. searchQuery moved in context() (v2.1.0+)
Breaking: searchQuery removed from top-level context() options. Use representationOptions.searchQuery instead.
// Before (v2.0.x)
await session.context({ searchQuery: '...' })
// After (v2.1.0+)
await session.context({ representationOptions: { searchQuery: '...' } })
17. Broader fetch retry logic (v2.1.1+)
The SDK now retries on all TypeError network failures (connection resets, DNS errors, etc.) instead of only those with 'fetch' in the message. No code changes needed — this is transparent.
Quick Reference Table
| v1.6.0 | v2.0.0 |
|---|---|
client.core | client.http |
getConfig() | getConfiguration() |
setConfig() | setConfiguration() |
getPeers() | peers() |
getSessions() | sessions() |
getWorkspaces() | workspaces() |
getDeriverStatus() | queueStatus() |
pollDeriverStatus() | Removed - do not poll |
peer.chat(q, { stream: true }) | peer.chatStream(q) |
peer.workingRep() | peer.representation() |
peer.getContext() | peer.context() |
peer.observations | peer.conclusions |
peer.observationsOf() | peer.conclusionsOf() |
session.getPeers() | session.peers() |
session.getMessages() | session.messages() |
session.getSummaries() | session.summaries() |
session.getContext() | session.context() |
session.workingRep() | session.representation() |
session.peerConfig() | session.getPeerConfiguration() |
session.setPeerConfig() | session.setPeerConfiguration() |
{ timeoutMs: 60000 } | { timeout: 60000 } |
{ maxObservations: 50 } | { maxConclusions: 50 } |
{ includeMostDerived } | { includeMostFrequent } |
{ lastUserMessage } | { searchQuery } |
{ config: ... } | { configuration: ... } |
message.peer_id | message.peerId |
message.created_at | message.createdAt |
peer.card() | peer.getCard() (card() deprecated) |
| (new) | peer.setCard(string[]) |
Observation | Conclusion |
ObservationScope | ConclusionScope |
| (new v2.1.0) | peer.createdAt / session.createdAt |
| (new v2.1.0) | session.isActive |
| (new v2.1.0) | session.getMessage(id) |
| (new v2.1.0) | page, size, reverse on list methods |
context({ searchQuery }) | context({ representationOptions: { searchQuery } }) |
Detailed Reference
For comprehensive details on each change, see:
- DETAILED-CHANGES.md - Full API change documentation
- MIGRATION-CHECKLIST.md - Step-by-step checklist
New Error Types
import {
HonchoError,
AuthenticationError,
BadRequestError,
NotFoundError,
PermissionDeniedError,
RateLimitError,
ConflictError,
UnprocessableEntityError,
ServerError,
ConnectionError,
TimeoutError
} from '@honcho-ai/sdk'
New Configuration Types
Configurations are now strongly typed:
await honcho.setConfiguration({
reasoning: {
enabled: true,
customInstructions: 'Be concise'
},
peerCard: { use: true, create: true },
summary: {
enabled: true,
messagesPerShortSummary: 20,
messagesPerLongSummary: 60
},
dream: { enabled: true }
})
FAQ
What does the migrate-honcho-ts skill do?
Migrates Honcho TypeScript SDK code from v1.6.0 to v2.1.1. Use when upgrading @honcho-ai/sdk, fixing breaking changes after upgrade, or when errors mention removed APIs like .core, getConfig, observations, or snakecase properties.
How do I install migrate-honcho-ts?
Run npx skills add https://github.com/plastic-labs/honcho --skill migrate-honcho-ts in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/migrate-honcho-ts/ (personal) or .claude/skills/migrate-honcho-ts/ (project).
Which AI agents can use migrate-honcho-ts?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is migrate-honcho-ts safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains migrate-honcho-ts?
It is published by plastic-labs in plastic-labs/honcho. It has 332 recorded installs.
More from plastic-labs/honcho
honcho-integration
plastic-labs/honcho
Integrate Honcho memory into existing Python or TypeScript codebases. Use when adding Honcho SDK, setting up peers, configuring sessions, and accessing Honcho's representation.
honcho-cli
plastic-labs/honcho
Inspect and debug Honcho workspaces via the honcho CLI. Use when investigating peer representations, memory state, session context, or dialectic quality — any task that requires introspection of a Honcho deployment, including verifying that a recall/record memory loop is actually working.
pre-pr
plastic-labs/honcho
Prepare a Honcho change for a pull request to plastic-labs/honcho. Invoke before opening a PR, when drafting a PR body, when asked if a branch is PR-ready, or when filling the pull request template. Checks required tests and docs, then writes Description / Proofs / Fixes.
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.