dsh-open-bots

Lasting bots for DeepSeek Harness. Each bot outlives the conversation and has its own name, photo, persona, memory, voice and model. You configure it by talking to it ("from now on your name is Ana", "be more direct", "use this photo"), and it runs on any model in your Harness catalog, open-weight models included. Behind each bot, a hidden brain follows the conversation and prepares what will help: it looks things up before you ask, and, when the bot plays a guiding role (therapist, teacher, coach), it leaves the bot techniques of that craft to apply in its own words.

Status: 0.1.0, the first public release. Tested on DeepSeek Harness 0.2.1-rc.3, Desktop and dsh web, on Windows. macOS is expected to work (no native modules, no shell commands) but was not tested. See Compatibility and CHANGELOG.md.

Language: the interface and the text the bots receive (persona rules, the brain's instructions, tool messages) are in Brazilian Portuguese for now, and the bots are tuned for conversations in Portuguese. The code, docs and comments are in English.

What it does
The brain
Voice
Responsible use
Requirements
Installation
Configuration
Credentials
Where your data lives
Compatibility
Development
Credits
License

What it does

A leader bot from the first start. It, and any other bot, creates new bots when you ask.
Identity by conversation. Ask a bot to change its name, title, persona, method, photo, model or voice, and it changes on the spot. Every change can be undone.
Memory in two layers:
- the persona, always present in the conversation;
- the facts, saved one by one by topic: a small memory goes into each turn whole, a larger one is searched automatically on each message.
Each bot has its own memory, plus a memory about you that every bot reads.
A light, live panel. A Bots panel in the sidebar shows each bot's photo, name and live state, with its settings (photo, model, permission, voice, leader, delete). "New conversation" is always in sight on each bot and at the top of its conversation. The panel opens at once with the last saved list and updates by itself.
Permissions under your control. A bot follows the access you chose for new conversations, and you can narrow it. To go past it, the bot asks for your "yes" on screen.
Bots talking to bots. A bot asks another one and gets the answer in the same turn.
Errors explained by the bot. When a model fails (quota, missing key, unknown model), the bot explains it to you in plain words in its next answer, and the panel shows a discreet mark.

The brain

Each bot has a brain: a hidden subagent that follows the conversation without ever talking to the person. What it finds reaches the bot as notes on a board that the bot reads before each answer, and the bot uses them as things it already knows.

Looks ahead. Tell the bot about a trip and the brain looks up the weather and things to do; hesitate between two products and it looks up prices and specs.
Guides by craft. When the bot plays a guiding role (therapist, teacher, coach, mentor), the brain leaves the technique of that craft for the moment, as an intent ("ask for the concrete scene, let the person choose where to start"), never as a ready-made line. The bot applies it in its own words and never mentions the brain.
Tasks on request. When something needs current data, the bot hands it to the brain as a task, says it will look, and tells the person when the result arrives.
Cheap when idle. A quick question to the model decides whether an exchange needs any work at all. Only then does the brain start, and it stays for the rest of the conversation, receiving each new exchange instead of a new brain being started every time (renewed after 30 exchanges or 20 minutes without one).
Nothing to configure. The brain uses the bot's own model. To change it, ask the bot ("use the Nemotron for your brain"); it applies to the brain's next piece of work.
Safe by default. The brain only searches and reads; it does not touch files, accounts or messages. If it fails twice in a row, it rests for 10 minutes and the bot carries on alone, as it would without a brain.

The design is in docs/brain.md.

Voice

Voice works with the speech service you already use. The plugin recognizes the service from the key: ElevenLabs, OpenAI, Groq, Mistral or Deepgram, or your own server in the OpenAI format.

Dictation in your language through the Harness's official microphone ("Voice input").
Each bot with its own voice. A Listen button on each answer reads it in the bot's voice. Voice and speed live in the bot's settings, with a sample, or the bot changes them when you ask. With ElevenLabs you can search its voice library in the bot's language, or create a voice from a description: the bot makes 3 previews, you listen and choose. Nothing is created or added unless you ask.
Live voice conversation. In a bot's conversation, the Voz tab turns into a face-to-face call: the bot's photo, a ring that shows who is speaking, the microphone open and the answer spoken while the bot writes. Talk over it to interrupt; everything stays written in the conversation. Needs a service with live listening and speech (today, ElevenLabs).

The design is in docs/voice-mode.md.

Responsible use

A bot is not a professional. Bots can take on roles like therapist or coach, and the brain helps them guide a conversation, but they are language models: they make mistakes, and they are not a substitute for a licensed professional. Do not rely on them in a crisis; look for local emergency services or a crisis line.
You choose the models. The plugin adds no content filter of its own; what a bot says depends on the model and the persona you give it.
Your conversations stay where your Harness runs, except what goes to the model provider and the voice service you configured (see Where your data lives).

Requirements

DeepSeek Harness >=0.2.1-rc.3 <0.3.0-0 (Desktop or dsh web).
At least one chat model configured in the Harness. The brain's web search uses the Harness's web search tool.
For voice (optional): a key for one of the services above, or your own server.

Installation

For people and for AI agents. Each step says what you should see; stop at the first step that does not match.

AI agents: never ask for a key in the chat, and never write one to a file yourself. Keys are the user's step (Credentials).

Get the package. Download dsh-open-bots-<version>.tgz from the latest release, or build it from the source (needs Node.js 20.6 or later and Git):
```
git clone https://github.com/dev-bravelo/dsh-open-bots.git
cd dsh-open-bots
npm pack
```
You should have a file dsh-open-bots-<version>.tgz. There are no dependencies to install.
Install it in your Harness profile. Either:
- in a Harness session, ask the agent to install the bundle from that file with the plugin manager (plugin_manager → install_bundle, with the absolute path of the .tgz); or
- close the Harness and run its command line, then open the Harness again:
```
dsh plugin --profile desktop add "file:<absolute path>/dsh-open-bots-<version>.tgz"
```
  The Desktop app uses the profile desktop.
You should see dsh-open-bots listed as installed and enabled.
- Stop if it is listed as incompatible-version: your Harness is outside the supported range.
Open the Bots panel in the sidebar. You should see the leader bot. Open its conversation and say hello; ask it to create another bot ("create a bot called Nina, a cheerful English teacher").
Optional: voice. Turn on Voice input in the Harness's Plugins panel. In the dsh-open-bots voice section (in the details of Voice input, or on the plugin's page), paste the key of your speech service. The plugin recognizes the service, tests the key there, stores it in the Harness credential vault and starts using it.

To remove it: uninstall the bundle with the plugin manager. Your bots' files stay in the data folder until you delete them (Where your data lives).

Configuration

Everything works without configuration. Optional settings go in your profile's patch file, <Harness home>/profiles/<profile>/cordis.patch.yml (a YAML list; add the entry to it):

- id: open-bots
  name: dsh-open-bots
  config:
    voice:
      language: en              # voice language when the bot's voice has none (default: the dictation language)
      default: Rachel           # voice of ordinary (non-bot) conversations for Listen
      cast:                     # voices given to new bots, in order (names or ids)
        - Rachel
        - Adam
      keyterms:                 # words live listening should recognize better (up to 50)
        - Nina
      delivery:                 # emotion tags in voice mode (ElevenLabs)
        intensity: natural      # sparse, natural or rich; `off: true` turns them off
        extra:                  # your own tags, by name
          shy: "[timid, hesitant]"
    cerebro:                    # a model for every bot's brain (default: each bot's own model)
      provider: <provider id>
      model: <model id>

<Harness home> is ~/.dsh, or $DSH_HOME when set. A bot's own brain model, chosen by talking to it, wins over cerebro. home sets another data folder (default <Harness home>/open-bots).

Credentials

Keys are referenced by name and read from the Harness credential vault when needed: never stored in the plugin's files, never sent to the interface, never asked for in a chat.

Service	Key name
ElevenLabs	`ELEVENLABS_API_KEY`
OpenAI	`OPENAI_API_KEY`
Groq	`GROQ_API_KEY`
Mistral	`MISTRAL_API_KEY`
Deepgram	`DEEPGRAM_API_KEY`

Paste a key in the dsh-open-bots voice section, or put it in the vault yourself, in <Harness home>/.credentials.yaml under refs:, or as an environment variable. For live voice, the interface gets single-use tokens that the host part creates from the key (valid for 15 minutes, one per connection); the key itself never reaches the interface.

Where your data lives

Everything stays in <Harness home>/open-bots/ on the machine where the Harness runs:

Path	What
`bots/<id>/persona.md`	the bot's persona
`bots/<id>/registro/`	the bot's facts, one file per topic
`usuario/persona.md`, `usuario/registro/`	what every bot knows about you
`bots/<id>/historico.jsonl`	identity changes, so they can be undone
`bots/<id>/fotos/`	the bot's photo, with earlier ones kept for undo

The brain's board lives in memory, for the current conversation only. The conversations themselves are ordinary Harness sessions. What leaves your machine: the requests to the model provider of each bot and of its brain, the brain's web searches through the Harness, and audio and text to the voice service you configured.

Compatibility

DeepSeek Harness: >=0.2.1-rc.3 <0.3.0-0 (engines.dsh). Tested on 0.2.1-rc.3, Desktop and dsh web, on Windows.
Official APIs only: the plugin does not patch the Harness application.
When the Harness updates: each module is a sub-plugin with its own dependencies, and what is not a public contract sits in a small adapter with its own test, so an update breaks a test, not your bots.
Known limit: the resident brain stays open while it waits for the next exchange. Hosts that wait for every subagent of a conversation to finish (headless runs, goals, the SDK wait, ACP) would wait for it until it is renewed (up to 20 minutes). Bot conversations are meant for the Desktop and dsh web.

Development

Command	What it does
`npm run hooks`	Points git to `.githooks/` (run once per clone)
`npm run test:harness`	Installs the published Harness in `dev/harness/<version>` (outside Git), once, and runs the tests against it
`npm test`	Unit tests, against the Harness installed by `npm run test:harness`
`npm run check`	Secret and personal-data scan, then the tests
`node scripts/ensaio.mjs`	Starts a test Harness (`dsh web`) in a separate folder with this package installed, without touching your own profile. Copy `.env.example` to `.env` for the model route and keys

Contributor and AI-agent rules are in AGENTS.md; the architecture is in docs/architecture.md.

Credits

DS Bot (Apache-2.0) was a reference for building lasting bots on the Harness. This project is independent.

License

Apache-2.0.

dsh-open-bots

Status: 0.1.0, the first public release. Tested on DeepSeek Harness 0.2.1-rc.3, Desktop and dsh web, on Windows. macOS is expected to work (no native modules, no shell commands) but was not tested. See Compatibility and CHANGELOG.md.

Language: the interface and the text the bots receive (persona rules, the brain's instructions, tool messages) are in Brazilian Portuguese for now, and the bots are tuned for conversations in Portuguese. The code, docs and comments are in English.

What it does
The brain
Voice
Responsible use
Requirements
Installation
Configuration
Credentials
Where your data lives
Compatibility
Development
Credits
License

What it does

A leader bot from the first start. It, and any other bot, creates new bots when you ask.
Identity by conversation. Ask a bot to change its name, title, persona, method, photo, model or voice, and it changes on the spot. Every change can be undone.
Memory in two layers:
- the persona, always present in the conversation;
- the facts, saved one by one by topic: a small memory goes into each turn whole, a larger one is searched automatically on each message.
Each bot has its own memory, plus a memory about you that every bot reads.
A light, live panel. A Bots panel in the sidebar shows each bot's photo, name and live state, with its settings (photo, model, permission, voice, leader, delete). "New conversation" is always in sight on each bot and at the top of its conversation. The panel opens at once with the last saved list and updates by itself.
Permissions under your control. A bot follows the access you chose for new conversations, and you can narrow it. To go past it, the bot asks for your "yes" on screen.
Bots talking to bots. A bot asks another one and gets the answer in the same turn.
Errors explained by the bot. When a model fails (quota, missing key, unknown model), the bot explains it to you in plain words in its next answer, and the panel shows a discreet mark.

The brain

Looks ahead. Tell the bot about a trip and the brain looks up the weather and things to do; hesitate between two products and it looks up prices and specs.
Guides by craft. When the bot plays a guiding role (therapist, teacher, coach, mentor), the brain leaves the technique of that craft for the moment, as an intent ("ask for the concrete scene, let the person choose where to start"), never as a ready-made line. The bot applies it in its own words and never mentions the brain.
Tasks on request. When something needs current data, the bot hands it to the brain as a task, says it will look, and tells the person when the result arrives.
Cheap when idle. A quick question to the model decides whether an exchange needs any work at all. Only then does the brain start, and it stays for the rest of the conversation, receiving each new exchange instead of a new brain being started every time (renewed after 30 exchanges or 20 minutes without one).
Nothing to configure. The brain uses the bot's own model. To change it, ask the bot ("use the Nemotron for your brain"); it applies to the brain's next piece of work.
Safe by default. The brain only searches and reads; it does not touch files, accounts or messages. If it fails twice in a row, it rests for 10 minutes and the bot carries on alone, as it would without a brain.

The design is in docs/brain.md.

Voice

Voice works with the speech service you already use. The plugin recognizes the service from the key: ElevenLabs, OpenAI, Groq, Mistral or Deepgram, or your own server in the OpenAI format.

Dictation in your language through the Harness's official microphone ("Voice input").
Each bot with its own voice. A Listen button on each answer reads it in the bot's voice. Voice and speed live in the bot's settings, with a sample, or the bot changes them when you ask. With ElevenLabs you can search its voice library in the bot's language, or create a voice from a description: the bot makes 3 previews, you listen and choose. Nothing is created or added unless you ask.
Live voice conversation. In a bot's conversation, the Voz tab turns into a face-to-face call: the bot's photo, a ring that shows who is speaking, the microphone open and the answer spoken while the bot writes. Talk over it to interrupt; everything stays written in the conversation. Needs a service with live listening and speech (today, ElevenLabs).

The design is in docs/voice-mode.md.

Responsible use

A bot is not a professional. Bots can take on roles like therapist or coach, and the brain helps them guide a conversation, but they are language models: they make mistakes, and they are not a substitute for a licensed professional. Do not rely on them in a crisis; look for local emergency services or a crisis line.
You choose the models. The plugin adds no content filter of its own; what a bot says depends on the model and the persona you give it.
Your conversations stay where your Harness runs, except what goes to the model provider and the voice service you configured (see Where your data lives).

Requirements

DeepSeek Harness >=0.2.1-rc.3 <0.3.0-0 (Desktop or dsh web).
At least one chat model configured in the Harness. The brain's web search uses the Harness's web search tool.
For voice (optional): a key for one of the services above, or your own server.

Installation

For people and for AI agents. Each step says what you should see; stop at the first step that does not match.

AI agents: never ask for a key in the chat, and never write one to a file yourself. Keys are the user's step (Credentials).

Get the package. Download dsh-open-bots-<version>.tgz from the latest release, or build it from the source (needs Node.js 20.6 or later and Git):
```
git clone https://github.com/dev-bravelo/dsh-open-bots.git
cd dsh-open-bots
npm pack
```
You should have a file dsh-open-bots-<version>.tgz. There are no dependencies to install.
Install it in your Harness profile. Either:
- in a Harness session, ask the agent to install the bundle from that file with the plugin manager (plugin_manager → install_bundle, with the absolute path of the .tgz); or
- close the Harness and run its command line, then open the Harness again:
```
dsh plugin --profile desktop add "file:<absolute path>/dsh-open-bots-<version>.tgz"
```
  The Desktop app uses the profile desktop.
You should see dsh-open-bots listed as installed and enabled.
- Stop if it is listed as incompatible-version: your Harness is outside the supported range.
Open the Bots panel in the sidebar. You should see the leader bot. Open its conversation and say hello; ask it to create another bot ("create a bot called Nina, a cheerful English teacher").
Optional: voice. Turn on Voice input in the Harness's Plugins panel. In the dsh-open-bots voice section (in the details of Voice input, or on the plugin's page), paste the key of your speech service. The plugin recognizes the service, tests the key there, stores it in the Harness credential vault and starts using it.

To remove it: uninstall the bundle with the plugin manager. Your bots' files stay in the data folder until you delete them (Where your data lives).

Configuration

Everything works without configuration. Optional settings go in your profile's patch file, <Harness home>/profiles/<profile>/cordis.patch.yml (a YAML list; add the entry to it):

- id: open-bots
  name: dsh-open-bots
  config:
    voice:
      language: en              # voice language when the bot's voice has none (default: the dictation language)
      default: Rachel           # voice of ordinary (non-bot) conversations for Listen
      cast:                     # voices given to new bots, in order (names or ids)
        - Rachel
        - Adam
      keyterms:                 # words live listening should recognize better (up to 50)
        - Nina
      delivery:                 # emotion tags in voice mode (ElevenLabs)
        intensity: natural      # sparse, natural or rich; `off: true` turns them off
        extra:                  # your own tags, by name
          shy: "[timid, hesitant]"
    cerebro:                    # a model for every bot's brain (default: each bot's own model)
      provider: <provider id>
      model: <model id>

<Harness home> is ~/.dsh, or $DSH_HOME when set. A bot's own brain model, chosen by talking to it, wins over cerebro. home sets another data folder (default <Harness home>/open-bots).

Credentials

Keys are referenced by name and read from the Harness credential vault when needed: never stored in the plugin's files, never sent to the interface, never asked for in a chat.

Service	Key name
ElevenLabs	`ELEVENLABS_API_KEY`
OpenAI	`OPENAI_API_KEY`
Groq	`GROQ_API_KEY`
Mistral	`MISTRAL_API_KEY`
Deepgram	`DEEPGRAM_API_KEY`

Where your data lives

Everything stays in <Harness home>/open-bots/ on the machine where the Harness runs:

Path	What
`bots/<id>/persona.md`	the bot's persona
`bots/<id>/registro/`	the bot's facts, one file per topic
`usuario/persona.md`, `usuario/registro/`	what every bot knows about you
`bots/<id>/historico.jsonl`	identity changes, so they can be undone
`bots/<id>/fotos/`	the bot's photo, with earlier ones kept for undo

Compatibility

DeepSeek Harness: >=0.2.1-rc.3 <0.3.0-0 (engines.dsh). Tested on 0.2.1-rc.3, Desktop and dsh web, on Windows.
Official APIs only: the plugin does not patch the Harness application.
When the Harness updates: each module is a sub-plugin with its own dependencies, and what is not a public contract sits in a small adapter with its own test, so an update breaks a test, not your bots.
Known limit: the resident brain stays open while it waits for the next exchange. Hosts that wait for every subagent of a conversation to finish (headless runs, goals, the SDK wait, ACP) would wait for it until it is renewed (up to 20 minutes). Bot conversations are meant for the Desktop and dsh web.

Development

Command	What it does
`npm run hooks`	Points git to `.githooks/` (run once per clone)
`npm run test:harness`	Installs the published Harness in `dev/harness/<version>` (outside Git), once, and runs the tests against it
`npm test`	Unit tests, against the Harness installed by `npm run test:harness`
`npm run check`	Secret and personal-data scan, then the tests
`node scripts/ensaio.mjs`	Starts a test Harness (`dsh web`) in a separate folder with this package installed, without touching your own profile. Copy `.env.example` to `.env` for the model route and keys

Contributor and AI-agent rules are in AGENTS.md; the architecture is in docs/architecture.md.

Credits

DS Bot (Apache-2.0) was a reference for building lasting bots on the Harness. This project is independent.

License

Apache-2.0.

dev-bravelo/dsh-open-bots

dsh-open-bots

Contents

What it does

The brain

Voice

Responsible use

Requirements

Installation

Configuration

Credentials

Where your data lives

Compatibility

Development

Credits

License

Community comments

dev-bravelo/dsh-open-bots

dsh-open-bots

Contents

What it does

The brain

Voice

Responsible use

Requirements

Installation

Configuration

Credentials

Where your data lives

Compatibility

Development

Credits

License

Community comments