Gitsona: A Self-Evolving AI Agent Living in Your Repository

Gitsona is an AI agent that runs inside a git repository and can write new tools for itself. It is the most experimental project in the Worksona portfolio.

The core premise is that a git repository is already a complete execution environment. It has state (committed files), scheduling (GitHub Actions cron), execution history (the commit log), and rollback (git revert). Gitsona takes this seriously and eliminates all external infrastructure dependencies: there is no database, no external message queue, no separate server required for the autonomous execution path. The agent runs on GitHub Actions' free tier indefinitely.

What is it?

The agent ships with nine production-ready tools: issue-manager, pull-request, code-analyzer, todo-manager, notification, scheduler, github, file, and ping. But the more interesting fact is in the first line of skills.yml:

# Auto-generated / edited by agent when tools change
- name: ping
  path: src/tools/ping.mjs
- name: issue-manager
  path: src/tools/issue-manager.mjs

That comment is not decorative. The file is the live tool registry, and the agent is designed to edit it.

Why is autonomous tool creation significant?

Most agents have a fixed tool surface. A developer defines the tools, deploys the agent, and the agent is limited to exactly what was anticipated at deploy time. This is predictable, but it means the agent cannot adapt to tasks that fall outside its original specification.

Gitsona's tool architecture inverts this. Tools are not registered in source code — they are entries in a YAML file. The agent core calls loadTools() at startup, which reads skills.yml and dynamically imports whatever modules are listed. If the agent writes a new .mjs file to src/tools/ and adds a line to skills.yml, that capability is available on the next run. The agent core never needs to change.

Each tool is a self-contained module: a schema export (for validation and documentation) and a run function (for execution). No base class, no framework decorator. A tool written in five minutes by the agent and one written carefully by a developer are structurally identical and coexist without coordination.

The compounding effect is the point. An agent that can only do what it was initially given reaches a capability ceiling immediately. An agent that can extend its own toolkit compounds: each new tool becomes a building block for the next task.

How does it work?

The memory system is the backbone. Gitsona models memory after human cognitive tiers:

Short-term memory (ctx.json) is overwritten on every run — it holds the current execution context. Medium-term memory (tasks.md) is a Markdown checkbox file; tasks are checked off as the agent completes them, and run logs accumulate as timestamped files. Long-term memory (knowledge.md) is append-only: patterns, principles, and domain knowledge the agent has learned persist across runs indefinitely.

Every state change produces a git commit. Task completions are prefixed agent:, memory writes are prefixed mem:. This means the full execution history of the agent is browsable in the GitHub interface without any additional observability tooling:

# See every task the agent has completed
git log --oneline --grep="^agent:"

# See every memory write
git log --oneline --grep="^mem:"

When memory volume grows large, a compression mechanism kicks in. Rather than deleting old entries by age, it computes pairwise Jaccard similarity between entries. Groups with similarity above 0.80 are collapsed into a single compressed entry that records the original count, time range, common themes, and sample entries. Frequency information is preserved even when individual entries are merged.

What guardrails exist?

The security model is minimal by design: the agent runs with whatever GitHub token scopes it is given, and the boundary of what it can do is set by those scopes — not by internal restrictions. This is intentional; the use case assumes a developer who owns the repository and is granting the agent access to their own infrastructure.

The practical constraints are:

• The agent cannot modify running infrastructure directly. It operates on repository files and GitHub API objects. Changes to live systems require a pull request that a human can review.
• All actions are committed to git. Nothing the agent does is invisible or undeniable. git revert is a complete undo.
• Failed tool loads produce a warning and skip, not a crash. An agent with a broken tool is degraded but still operational.

The fleet management layer — a web dashboard backed by an Express API server — allows multiple Gitsona instances to be provisioned and monitored from a single interface. Agents are created from a template repository via GitHub API automation, meaning a new agent goes from "I want one" to "it is running" in minutes without manual repository setup.

Gitsona is the most open-ended project in the portfolio precisely because its surface area is designed to grow. The nine initial tools are a starting point. Where the agent takes it from there depends on what tasks it encounters and what gaps it decides to fill.