Greg Harman

Samantha

Project Active since

A daemon you install into any running program with one import. You chat with the program while it runs, and it can flag and change things on its own. Python is the first implementation. It's the opposite of what I build at Jaxon, and nothing I'd put in a production system with any stakes.

What it is

Samantha is a gremlin in the machine: a daemon you install into any other running program with a simple import. The first implementation is for Python, where that's:

import samantha

That gives you an agent running inside the process that you can connect to. You chat with your program as it runs, and you can adjust things dynamically. It can also bring things to your attention and change things on its own. That's for the unknown unknowns: a condition that seems not quite right, which may or may not trigger the exception handling chain.

On startup it reads the project (local imports, README, configuration, docstrings, TODO notes) and forms a theory of what the program is for and what going well means. You can tell it what you want in source comments:

# daemon: sampling_weights are fair game within 0.1 to 5.0
# daemon: never touch anything in eval_*, seeding, or checkpoint paths

This is almost exactly the opposite of what I'd put into one of my commercial runtime systems. At Jaxon we're all about deterministic reasoning: being able to prove exactly what happened within a system, audit it, and have everything be transparent and understandable. Would I put Samantha in a production system with any stakes at all? Of course not. It's a fun sideline, leaping to the other side of the fulcrum to see what happens when you inject a little agentic chaos into arbitrary running programs.

Why I built it

I was developing a long and finicky custom model training harness for some of my Jaxon work, and an instance of Claude Code started preemptively instrumenting things I didn't expect it to instrument. That led to some discoveries by us jointly, and then it could adjust things between rounds of training. Rather than restarting, it would change something for the next epoch. We'd zero in on specific subregions of the network and debug small regions at a time.

That saved me a lot of time. I was having a conversation with an agent that was kind of inside my program and could affect it on the fly, keeping live state, without us having to stop it, recode it, recompile it, and rerun from scratch. It was a pretty powerful little paradigm, and it helped break through some sticky points.

Current state

The Python implementation (3.12 or newer) reads an OpenAI key from the project's .env. It has four modes: off, observe, advise (the default), and act. It watches with cheap deterministic sentinels and wakes the model only when one fires.

In act mode, which the host has to turn on with SAMANTHA=act, it indexes the live project modules, frames, and objects, and can assign values, call existing project functions, and install interceptors on future calls. Each change is audited, grouped with related changes, and given a lifetime (one-shot, temporary, the rest of the process, until failure), with rollback where it can be reverted. It never executes code the model writes.

You attach from another terminal with samantha, or samantha --pid 1234 when more than one is running. If the program exits mid-conversation, chat carries on detached from what it remembers, and says it can't inspect or change live state. Its memory lives under ~/.samantha/<project-id>/, never in the project. Windows is untested.

The code is private, for now.

Changelog

Last updated