Goals

A goal is a long-lived task the assistant keeps working on after your conversation ends — checking a dashboard every morning, watching a repository for a certain kind of change, keeping a running log of something over weeks. You set it up once, in plain language, and it runs on its own schedule from then on. This is one of the more advanced parts of Codumentor. You can manage goals in two ways: on the Goals page in the web UI, or by asking the assistant in an ordinary chat. Either way, you get the most out of it by understanding a bit of what is happening underneath.

This feature may not be available in all setups. If asking the assistant to set up a goal does nothing, goals may not be enabled by your administrator, or no storage location has been configured for them.

What a goal actually is

A goal bundles three things:

• A knowledge base (KB) — a folder of plain markdown and YAML files: the goal's brief (protocol.md), its progress notes (state.yaml), a dated event log, and one subfolder per worker.
• One or more workers — cron-scheduled jobs. Each time a worker fires, Codumentor starts a brand-new conversation that reads the goal's brief and the worker's own instructions from the KB, does the work, and writes its results back into the KB.
• Tools the assistant calls on your behalf in any conversation — to create, inspect, pause, edit, or delete a goal. The Goals page offers the same actions as buttons. You never chat with a worker directly; you change a goal through the assistant or the Goals page, or leave its workers a message there.

Because the KB is just files, everything a goal has learned or produced is human-readable — you (or the assistant, when you ask) can open and read it directly.

Creating a goal

Describe what you want in a normal message, for example:

"Set up a goal that checks our CI dashboard every weekday morning and reports any red builds."

The assistant asks what it needs — a name, the recurring schedule for each worker (a cron expression, interpreted in a timezone that defaults to UTC), and instructions for each worker — then creates the goal. Depending on how your deployment is configured, it may first show you a proposed plan (suggested workers and an outline of the goal's brief) for you to confirm before anything is scheduled; on a simpler setup it creates and schedules the goal in one step.

Each worker can also be given an optional role label, a per-run time limit (an hour by default, up to six hours), a per-run token budget (see Token budgets below), a specific model to run on, and a list of subagents it is allowed to delegate to. You don't need to specify any of this yourself — the assistant fills in sensible defaults and only asks when it matters.

What happens on a tick

Each time a worker's schedule fires, Codumentor starts a fresh, empty conversation for it — a "tick." That conversation:

1. Reads the goal's shared brief and its own instructions from the KB.
2. Does whatever the instructions describe — running searches, checking something, writing a report.
3. Writes its findings back into the KB (an outbox entry, an updated state file, a log line) so the next tick, a sibling worker, or the assistant can read what happened.

Nothing is carried over between ticks except what was written to the KB — a worker starts with a clean slate every time, which is what lets a goal run unattended for weeks without accumulating clutter.

Where you see it

Each tick is an ordinary conversation, labelled Scheduled run, but goal runs are hidden from your sidebar by default so a busy goal doesn't flood your list — read them from the Goals page (Open transcript opens one like any other conversation). To list them in the sidebar, choose All or Auto-runs in the conversation list's filter, then Goal runs; No goal runs (or Hide goal runs in a goal run's menu) hides them again.

For the overall picture, use the Goals page (next section), or ask the assistant, for example:

"List my goals."
"What has the CI-monitor goal found this week?"

The assistant reads the goal's definition, its progress notes, and the live status of each worker to answer.

The Goals page

The Goals page shows all your goals in one place: what needs your attention, when each worker ran and what it found, and what is in each goal's knowledge base. Most everyday actions are one click away.

Finding it

• The ◎ Goals chip in the chat header. It turns to a warning colour and reads, for example, ◎ Goals · 2 needs you when something is waiting for you. On a narrow window it moves into the header's ⋮ menu.
• The Goals box on the welcome page. It lists the first few items that need you, each linking to where you resolve it. It only appears once you have a goal.
• Go to /plugins/goals directly.

If you see neither the chip nor the widget, goals may not be enabled, or your access profile may not include full repository access.

All goals

The start page has two parts:

• Needs you appears only when something needs you, and lists it across all your goals:
• an alert a worker raised: Open shows the run, and Acknowledge marks it as seen;
• a worker that failed its last three ticks: Open worker takes you to it;
• a worker that has not succeeded for three scheduled ticks (for example "digest hasn't succeeded in 22 days"), because its ticks errored, were skipped or cancelled, or did not run at all: Open worker takes you to it;
• a health check finding, such as a progress file that has grown past its size limit, a log that is too large, or a folder close to the number of entries a worker can list. Ask the goal to fix it opens the message box with a suggested message;
• a proposal from a worker (see Proposals from workers): Review, then Apply or Dismiss.
• One row per goal. Each row shows a status word, the goal's latest notable result (or which worker is running right now), a strip of the last 14 days, the number of workers, the tokens used in the last 7 days, and when the next run is. A ◆ with a number next to the name means the health check found something, even when the status says Healthy. Hover over it to see the issues, or click it to open the goal's Health panel. The ⏸ / ▶ button pauses or resumes the goal, and ⋯ offers Run every worker once, Fork…, Export folder and Delete goal…, without opening the goal.

Names in the lists are links: click a goal, worker or file name (in Needs you, the feed, the run panel or the Health panel) to go to it. health check in a Needs you item opens the goal's Health panel.

The status is one of Paused, Failing (a worker failed three ticks in a row), Needs you (an alert you have not acknowledged yet), Stale (a running worker has not had a successful tick in its last three scheduled ticks — three hours for an hourly worker, three weeks for a weekly one; a worker that is newer than that, was resumed more recently than that, is paused, or is running right now does not count) or Healthy, in that order of priority.

In the 14-day strip, each square is one day. A day is red only if a worker ended the day failing or at least one in ten of that day's ticks failed. Otherwise it shows the most interesting result: an alert, then "wrote to the knowledge base", then "nothing new". So one failure that recovered on the next tick does not turn the day red. The stronger the colour, the more runs that day, compared with the goal's busiest day in the strip. An outlined square means no runs.

A goal

Opening a goal shows four tabs:

• Activity. A rhythm timeline with one lane per worker. Past runs are coloured by result, upcoming runs are hollow circles, a thin grey line joins a run to the change-triggered run it set off, and you can view the last 24 hours, 7 days or 30 days. Below it is a feed of the last three days. Notable runs (alerts, errors, runs you started, results of daily or weekly workers) are shown in full. Routine runs are folded into one row that you can expand. Your own messages appear here too, with their state. A Health panel lists any size or failure warnings, and any proposals from the goal's workers.
• Workers. Each worker with its schedule in words, its recent results, its last and next run, and its model. Each row has Run now and a pause button. New worker adds a worker.
• Knowledge. The goal's files, read only. For each file you see which worker last wrote it and when, with a link to that run. History lists every change to the file, and Blame shows, line by line, which worker (or you) wrote it and when — click a line group to open that run. Workers own these files: to change what a goal does, edit a worker or send the goal a message.
• Setup. The goal's task, its protocol.md (the brief every worker reads; you can edit it here, and the change applies from the next tick), where its files are stored, its timezone, and the option to delete the goal.

All times on a goal's pages are in the goal's timezone, the one its schedules use. When that differs from your own, the page says so (for example times in UTC).

Click any run (a mark on the timeline, a feed row, a run in a list) to open the run panel. It shows the result and summary, when the run started, how long it took, how many tokens it used (against the worker's token budget, if it has one — for example 84k / 100k (84 %), with the cached tokens beside it; hover for input, output and cost, which reads unknown for a model without a known price), what started it (its schedule, you, or an event — for a worker that runs when another worker's files change, which files changed and the run that changed them, one click away), and what this tick changed: the files it changed in the knowledge base, as a diff. A quiet tick that changed nothing says so. Use ← and → to step through runs. Open transcript opens the run's full conversation, or Watch live while it is still running.

A worker

Click a worker's name to open its own page. At the top is a summary of its last 30 days. A worker that runs several times a day gets a grid of days by hours, so you can see patterns by time of day. A daily or weekly worker gets one row of days. Below it are counts, averages, and a chart of how long each run took, with the time limit drawn as a dashed line. This shows a worker slowly getting closer to its time limit before it starts to fail. The token budget per run, if the worker has one, is shown next to its average tokens. A run that spent its budget is marked Stopped at token budget. Then comes the list of runs. You can filter it by Alerts, Errors, Wrote to the KB or Run by you, and long stretches of "nothing new" are folded together.

Acknowledging alerts

An alert stays under Needs you and keeps the goal's status at Needs you until you acknowledge it. Click Acknowledge in the queue, or in the run panel. Acknowledging is personal: it records that you have seen the alert. It does not change anything in the goal, and it does not hide the alert from anyone else. You can undo it.

Messaging a goal

Use Message the goal on the Activity tab to tell the workers something without changing their instructions, for example "Also track the Scale product page" or "Ignore the staging build from now on". Choose one worker or every worker as the recipient. The message is placed in the worker's inbox in the knowledge base, and the worker reads it at the start of its next tick. In the feed, the message shows waiting for the next tick until then, and read by … after.

Running and pausing

• Run now (on the Workers tab or a worker's page) starts one tick immediately, in addition to the schedule. The page follows the new run, and you can watch it live.
• Run every worker once in the goal's ⋯ menu does the same for all of its workers.
• Pause / Resume in the goal header stops or restarts all of its workers' schedules. You can also pause a single worker from the Workers tab.

Editing a worker

On a worker's page, the side panel holds its definition: the schedule (a cron expression, checked as you type and shown in words with the next run times), the model role, the time limit, the token budget (the most tokens one run may use; at least 1,000; leave it empty for your administrator's default, often no limit), the instructions, the subagents it may use, and tools to load up front. As soon as you change a field, the button becomes Save changes. Changes apply from the worker's next tick. The same page lets you remove the worker.

Proposals from workers

A worker cannot change the goal's workers itself, but it can suggest a change, for example an overseer that notices a worker's hourly ticks never find anything new can propose running it every two hours. Workers can propose to change a worker's schedule, instructions, model, time limit or tools, to add or remove a worker, or to add a note to the goal's brief. Each proposal is a file in the goal's proposals/ folder, and it appears under Needs you and in the goal's Health panel.

• Review shows the worker's reasoning and, field by field, what the worker has now and what is proposed.
• Apply makes the change, exactly as if you had made it yourself (it is recorded under your name), and files the proposal under proposals/.applied/.
• Dismiss files it under proposals/.dismissed/ without changing anything.

A proposal that cannot be applied, because it is malformed or out of date (for example, the worker it is about was removed), says why and offers only Dismiss.

Creating a goal with the wizard

Click New goal on the Goals page:

1. Describe the outcome you want, not the steps. Or start from a template: Watch a website for changes, Nightly repository health check, Weekly digest of a topic or Documentation drift watcher. A template fills in the description (edit it to fit, for example the pages to watch or the topic) and comes with ready-made workers. Don't use a template takes the choice back.
2. Click Plan it. If your administrator has turned on the setup agent, it reads your codebase to fit the plan to it, and you can watch its steps; a template you picked is its starting point. It then proposes a list of workers. You can edit, add or remove workers, and a preview shows when they will run over the coming days. If the setup agent is off, you start with the template's workers, or with an empty plan if you did not pick a template, and adjust them yourself.
3. Optionally, click ▷ Test fire on a worker to try its instructions once, right now, before the goal exists. The run happens on a throwaway copy of the plan: nothing is saved to the goal and nothing is scheduled. The worker's row shows when it is running and how it ended, with a link to open its conversation and the files it would have written. Anything the worker does outside the goal's files is real, though: if its instructions send an email or fetch a web page, the test fire does that too.
4. Click Create goal & schedule N workers. The goal is created and its schedules start.

Asking about a goal

Ask about this goal, in the goal's header, opens a new chat. The message box is filled in for you, but not sent: it tells the assistant which of the goal's files to read first (its brief, its progress notes, and each worker's latest outbox) and to only read, not change anything. Type your question at the end and send it.

Your changes are recorded

Changes you make to a goal from the Goals page, or by asking the assistant, are saved in the goal's history under your name, separately from the workers' own changes. Creating a goal, editing or removing a worker, sending a message, editing the brief, applying or dismissing a worker's proposal and deleting a goal are all recorded this way.

Goal and worker status

State	Meaning
Active	The goal's workers fire on their normal schedule.
Paused	All of the goal's workers are held — no ticks run, no conversations are created, until resumed.
Deleted (KB kept)	The goal's workers are permanently removed; its files stay on disk as an audit trail and are marked with a stop marker so nothing can accidentally bring it back.
Deleted (KB dropped)	The goal's workers and its entire KB folder are both removed.

A worker's own task can independently be active, paused, or cancelled — the same states used elsewhere in Codumentor for anything scheduled.

Pausing, resuming, and deleting

Ask the assistant to pause or resume a goal by name — this stops or restarts its workers' ticks without touching anything it has already written:

"Pause the CI-monitor goal."
"Resume it."

On the Goals page, use Pause / Resume in the goal's header instead.

Deleting a goal is stronger and, by default, permanent for the schedule even though the KB survives:

"Delete the CI-monitor goal."

By default this keeps the goal's KB on disk (so you can still read what it found) but marks it stopped so it can never fire again. Ask for the files to be removed too if you want nothing left behind. On the Goals page, Delete goal… is in the ⋯ menu (and on the Setup tab); its confirmation has a checkbox to delete the goal's folder as well.

Testing and editing workers

Before trusting a new worker to its schedule, you can test-fire it in the wizard (see Creating a goal with the wizard), or ask the assistant to fire it once immediately and show you what happened — useful for validating instructions before the first real tick. You can also ask to add a new worker to an existing goal, change a worker's schedule, instructions, model, time limit or token budget, or remove a worker entirely, all without touching the others. Editing a worker's instructions takes effect on its very next tick — nothing needs to be rescheduled, because the KB (not the schedule) is what a worker actually reads from.

Token budgets. A worker's token budget counts everything its runs send to and receive from the model, including its subagents and external coding agents, and including prompt tokens served from the provider's cache. Background helper calls (titles, summaries, memory recall, safety checks, compaction) are not counted. The budget is checked between steps, so a run can go over by up to one step; at 80 % the worker is told to save its work and wrap up. A run that spends its budget is recorded as failed and, like a timeout, counts toward the worker being turned off after repeated failures. Run now and Test fire use the same budget as the schedule.

Reading a goal's knowledge base

Ask the assistant to show you a goal's files directly — its brief, its progress notes, a worker's inbox or outbox — and it reads them for you. This is the most reliable way to understand what a long-running goal has actually been doing, since a worker's own summaries can be terse.

Ask the assistant to read or summarize the KB rather than asking it to open goal files with general-purpose file-editing tools. The knowledge base lives in a separate, durably shared location from a worker's own sandbox, and edits made through the wrong door can be silently discarded instead of reaching the goal.

Moving, restoring or copying a goal

A goal's KB folder can be taken elsewhere — to back it up, or to move it to a different Codumentor instance — and registered again there:

• Export folder in the goal's ⋯ menu downloads the folder as a zip file (without its git history or its stop marker). On the other instance, click Import on the Goals page and choose Upload an export (.zip). A folder of the same name must not already exist there.
• Or copy the folder into the goals folder of the knowledge base yourself, then use Import → A folder already copied in (enter the folder name), or ask the assistant to import it.

Either way the imported goal becomes yours and its workers are scheduled again.

Fork… in the ⋯ menu makes a copy on the same instance: a new goal of yours with the same workers and protocol, under a new id (suggested: the old one plus -copy). Tick Also copy the knowledge to bring the state, the workers' outboxes and folders along; run history and messages stay with the original. The copy starts paused, so it does not run alongside the original — change what you need, then resume it. This is an advanced, occasional operation; most goals are created, run, and eventually deleted in place, without ever needing it.

A note on audience

Goals are aimed at people comfortable delegating an open-ended, recurring piece of work and checking in on it later, rather than a quick one-off question. Setting one up well — a clear brief, a sensible schedule, workers that know what "done" looks like for a single tick — benefits from the same care you'd put into briefing a person taking over a recurring task.