What is an ecosystem

An ecosystem gives your AI agents a wiki they're told to read before every task and to add to after it. Your people read the same wiki in Obsidian. It works for one person with a few repos or for a whole company, and it runs on your own machine.

Just want an agent pane for each repo? Quickstart does that in seconds. An ecosystem adds the memory and the team.

What is an ecosystem (1 min 35 s). Real ACTower screens, sample data. Recorded 2026-10-29.

Three layers

  • The hub collects. It's a lens, not a home: every doc, agent and skill in it is a link into a role repo. You can rebuild it from scratch at any time and lose nothing.
  • Role repos own the knowledge. Each department is its own repo. A new ecosystem starts with devtools, product, sales, marketing and admin, and you can add strategy and support.
  • Code repos hold your code. The ecosystem points agents at them; it doesn't absorb them.

The hub is your agents' wiki

  • Each agent has a home. A specialist's folder in its role repo holds a reference folder for what lasts (playbooks, proven patterns, a changelog) and a dated folder for each piece of work, so decisions don't die in chat or pull-request threads.
  • The hub links them all into one tree. On disk these are plain folder links (symlinks): docs/sales-related in the hub points into the sales role repo, so Finder, your editor and your agents all see one tree. No copies of your knowledge, so nothing drifts. Docs folders are linked whole, so a new page appears in the hub right away.
  • Every agent starts from the same rules. The hub's CLAUDE.md, which Claude Code and Cursor read, tells each agent to read its reference folder before starting, write up the work in a dated folder, and move what lasts into the reference folder.
  • So the wiki compounds. Your devtools agent finds that the staging deploy needs a cache flush and writes it in its reference folder. Next week a different session reads it before deploying.
  • You can see where every page comes from. The source map in ACTower traces each file in the hub to the repo that owns it, and flags broken links and strays. View it By repo (each role repo and the links the hub makes into it) or By folder (the hub's own tree).

One hub, two readers

  • Agents read it through their AI CLI. The hub's agents, skills and commands sit where Claude Code and Cursor look for them, so open the hub and they're there.
  • People read it in Obsidian. Open in Obsidian on the ecosystem opens the hub as a vault: the agents' reference pages, their dated work folders and the agents' own definitions, as normal pages. A hub page is a link to the role repo's file, so editing it in Obsidian edits the role repo, and the agents read your version next time.
  • A dashboard that keeps up. ACTower builds the vault a Dashboard: the last 20 files changed across the wiki, recent discussion files, a section for each agent with the latest 20 files in its own folder, and file counts. So you see what each agent has been writing without opening a terminal. While the workspace is running, a small helper (vault-sync, started by Start workspace) tells Obsidian within seconds when an agent writes a doc in any role repo, so the Dashboard updates as the work happens.

Each person gets the slice they need

On a team, a profile is a role, like Frontend developer or Sales. You create the profiles and choose what each one holds: repos and a level for each (View only, Propose changes or Can edit), never people; several people can share it. A person's hub links only the role repos in their profile, so their agents' wiki, and the agents themselves, are exactly that slice. For example, you might set them up like this:

  • Frontend developer: devtools and product, and the web code. Their agents never see the sales pipeline or the admin docs.
  • CTO: every department, and all the code.
  • Sales: sales, marketing and product, and no code.

On a team, the wiki is git underneath: every page has history, your agents' new pages stay on your machine until you share them, and teammates bring them in with Get updates.

What ACTower does around it

  • Create from one short name. A dry run lists every folder, link and file before anything is written.
  • Start workspace opens the team's terminal sessions with a window for each agent. Tick Also launch agents to start them in your AI CLI. Claude Code loads each specialist; other CLIs start plain. Monitor and Responder watch them from the first minute.
  • Autopilot can use your specialists as reviewers, or as the developer. See Autopilot.
  • Rebuild picks up a new agent, skill, command or docs folder made outside ACTower, by hand or by an agent. Add agent and Add repo update the hub for you, and new pages in existing folders appear without it.

What it is not

  • Not a cloud service. ACTower runs on your machine. A team shares through private GitHub repos you own; ACTower creates them and pushes only when you ask (Put on GitHub, Invite, Share).
  • Not a separate copy. Editing a page in the hub, in Obsidian or your editor, edits the role repo's file. Just don't create files at the hub's top level: a file with no role repo behind it is a stray, and the source map flags it.

Create your first ecosystem

The step-by-step guide, with its own video, is on Create your first ecosystem. The rest of this page is the full guide: why the architecture works, the CLI, working with existing repos, and the FAQ.

Why this architecture — the beauty of the result

What you end up with is not a pile of config. It is a structure with a point:

  • Role repos are the source of truth. Each role — API, sales, ops — owns a real repository. The work, the docs, and the agent for that role live where that role's people already work. Nothing is invented in a place no one looks.
  • The hub sees everything without owning anything. The hub is a documentation hub assembled entirely from symlinks into the role repos. It aggregates every repo, dashboard, and knowledge base into one workspace — but it holds no canonical copy. Edit a role repo, rebuild, and the hub reflects it. Delete the hub and you have lost nothing.
  • The source map is the live proof. Because the hub only symlinks, the source map can trace every file back to the repo that owns it. You can always answer "where did this come from?" — and catch strays before they rot.
  • The knowledge base is browsable. The same structure opens as an Obsidian vault, so the humans get a readable knowledge base for free, kept in sync with the repos.
  • Decisions get a home that compounds. Real work produces discussions — design debates, audits, reviews, incident notes. They cannot live forever on a code repo: they pollute it, and they die in PR threads. In the hub they land in dated discussion folders (YYYY-MM-DD-topic, timestamped files), stay findable, and become the reference folders your specialists re-read before new work. The archive is not storage — it is the memory your agents actually use.
  • Agents come in two layers. Every role repo carries its specialist (sales, marketing, ops). Your code repos get both layers: a developer agent that works inside the repo — focused, code-context only — and one or more specialist agents defined at the hub for that repo. The asymmetry is the point: each specialist owns a reference folder in the hub — implementation plans, PR reviews, bug diagnoses, production postmortems, audits, and a curated reference/ of the domain's playbooks — far bigger than what the in-repo developer carries, and it grows with every piece of work. The developer stays lean; the specialists accumulate institutional memory. Both layers are discovered natively by your CLI, with the right slash commands and skills already in place. (It is how we run ACTower: the api repo pairs an in-repo developer with an API specialist whose reference folder deepens every week.)

Two principles run through all of it. Nothing happens silently: the dry-run lists every change before anything exists, every applied step is disclosed, and deregister never deletes a file — you can always see what ACTower is about to do and what it did. And the same app that builds the workspace governs it: the ecosystem you create is the one the Monitor watches, so safe agent actions auto-approve and risky ones wait for you, from day one, in one place.

And it scales from one project to a company without changing shape. One person with three repos and a company with thirty use the same structure, scaled to fit. Teammate hubs with scoped visibility — where each person sees only their slice — are built on the same role-repo-plus-symlink model you get on day one: invite someone with a profile, and their hub links only the repos that profile allows.

The CLI path

Create the ecosystem in the app. After that, the terminal can do the rest:

actower ecosystem list                                   # your ecosystems
actower ecosystem repo add --kind role|app --path <dir>  # add a repo you already have
actower ecosystem repo open <repo> --cli claude          # start an agent in a repo's folder
actower ecosystem hub --config <yaml> --profile <name> --rebuild --execute   # Rebuild

The exact Rebuild command for your hub, with its config path and profile, is near the top of the hub's CLAUDE.md ("To refresh this hub"). Run actower ecosystem --help for everything on your installed version.

Working with existing repos

You do not have to start from a blank machine. ACTower meets your existing code where it is:

  • The wizard suggests role repos. At creation, the wizard scans your workspace and suggests role repositories it finds, and includes an App repos step so you can point it at the code that already exists. You pick which of them become roles in the ecosystem.
  • Adopt a whole existing ecosystem. If you already have a hub-shaped workspace — a legacy or hand-built one — ACTower can adopt it: it builds a read-only source map of what is there, so you get the live view without restructuring anything. Adoption never rewrites your layout.
  • Add a repo to an ecosystem you already created. Open the ecosystem, choose Manage, then Add repo: the hub is re-linked to include it, and the dry-run preview shows every change before anything is written. Adding a repo is the ecosystem owner's action; members do not see it in their hub.

FAQ

Will my global ~/.claude/CLAUDE.md be affected?

No. The scaffold writes only inside the workspace it creates — there are zero references to ~/.claude anywhere in it. The hub and each role repo get their own CLAUDE.md, inside the workspace. Claude Code layers a global ~/.claude/CLAUDE.md with per-project files, so your global instructions keep applying untouched; the ecosystem's files simply add project-level context on top.

How are agents recognized?

Hubs ship .claude/agents, .claude/skills, and .claude/commands as symlinks into the hub's docs/claude-* folders. Claude Code discovers agents, skills, and commands natively at the hub level — no registration step, no plugin to install. Open the hub in your CLI and they are just there. And because the definitions live under docs/ rather than a hidden dot-folder, they are part of the knowledge base itself: open the vault in Obsidian and you can read or edit any agent, skill, or command like a normal doc.

What about Cursor?

Supported. Cursor reads the hub's commands and agents natively — the same .claude locations Claude Code uses, symlinks and all — so your slash commands work in Cursor as-is, and your specialist agents appear there as invokable subagents.

What about Codex and Antigravity?

Today, hub commands and instructions are supported in Claude Code and Cursor. Codex and Antigravity support is coming.

What gets created, and where?

Everything lives inside the workspace you name at creation:

  • <name>-ecosystem/ — the hub: docs/claude-* content, the .claude/{agents,skills,commands} symlinks, and the hub's own CLAUDE.md. The person who creates the ecosystem gets this full view of every role repo; each invited member gets a scoped hub showing only that person's slice.
  • One repository per role — each with its own CLAUDE.md and the files that role owns.
  • An Obsidian vault over the hub, and the ecosystem.yaml that describes the whole thing.

Nothing is written outside the workspace. (See the first FAQ answer for ~/.claude.)

How do I remove an ecosystem?

Deregister it. Removing an ecosystem from ACTower deregisters it — it drops out of the Ecosystems list — but never deletes your files. Your hub and role repos stay on disk exactly as they were; you delete them yourself, if and when you want to.

Does this touch my git remotes?

Only when you ask. Creating an ecosystem is local-only: folders, files and links on your machine, with no remotes and no pushes. GitHub comes in when you connect it for a team. Then ACTower creates private repos under your account or organization and pushes to them when you choose Put on GitHub or invite someone. It adds an origin remote to your own copy only if it has none. If your copy's origin points at another repo, Put on GitHub asks you first which repo is the team's; pick the new one and your old remote is kept as previous-origin. Invites and revokes add and remove each person's deploy keys. Your GitHub token stays on your machine and is used only for admin steps like these, never for your own pulls and pushes. Sync all never sends anything; Share, Send for review and accepting a proposal do, one repo at a time.