Grepoworks documentation

Getting started

1. Install Tampermonkey for your browser, then install the Grepoworks userscript from the download page.
2. Open your Grepolis world. A prompt appears asking for your licence code — paste it once. You get the code in your dashboard after buying a plan or starting the free trial.
3. Click the Grepoworks button in the bottom-left of the game to open the panel.
4. Press Seed base profiles on the Account tab. That gives you a working set of profiles to edit instead of a blank slate.
5. Assign your cities under Profiles → City assignment, then switch on the automations you want.

Nothing runs until you switch it on. Every automation has its own enable toggle, and they are all off by default.

The panel

The header carries Log, Intel, Profiles, Account and Report an issue, plus the language picker. Below that are the tabs:

Poll interval (seconds) on the Profiles tab sets how often the bot looks at the game, between 10 and 20 seconds. Leave it at the default unless you have a reason not to.

Two things are not where their name suggests. Island quests live on Culture & ✴️ Quests, not Island — that tab is also where you say which quests each city may take. And cave silver is a sub-tab of Combat, because putting silver out of reach is a defensive move.

Profiles

A profile is a city specialisation. You build the profile once and assign it to as many cities as you like — every assigned city follows the same three schedules.

Automation

The master switches: Auto-build enabled, Auto-research enabled, Auto-recruit enabled and Hero dispatch enabled. Off here means off everywhere, whatever a profile says.

Hero dispatch

Hero dispatch enabled moves city-effect heroes — the ones whose bonus applies to a city's own building, recruiting or culture work — to whichever city that bonus is worth the most in. Combat heroes are never moved: they earn their keep riding with an army, and the cities they sit in are left alone so a dispatch cannot evict one.

The judgement is about future work, not outstanding work. A hero's bonus applies at the moment an order is placed, not to orders already sitting in the queue, so a city whose queue is already full of the work scores nothing. What counts is what that city will still be ordering between the hero's arrival and the end of its stay.

A move takes real travel time, so the bot will not shuffle a hero for a marginal gain: a destination has to beat both the hero it would displace and the value of where the hero already stands, by a clear margin, and each hero has a cooldown between moves. Pick which cities may receive one with Send heroes to these cities in the profile's automation overrides.

The three schedules

Sub-tabs Buildings, Research and Troops hold Profile buildings, Profile research and Profile troops. Each row has a Target and a Prio: the target is the level or troop count you want, the priority decides what gets done first when resources are short.

Build focus

Two shortcuts push one goal to the front of everything else:

• Rush Academy 28 before Conquest research — gets Conquest unlocked as early as the city can manage, by treating Academy 28 as the only thing that matters until it is done.
• Focus colonization ship research and build — drives the whole colony-ship chain: the Ceramics and Colonization research, the Harbour, the population, and finally the ship itself.

A focus clears its own way

This is the part that makes the shortcuts worth using. "Rush the Academy" does not mean "queue the Academy and hope" — each cycle the bot asks what is actually standing between the city and the next Academy level, and fixes that instead, then returns to the main goal on its own. In practice it handles four kinds of obstacle:

The requirement levels used are the game's real ones, and only ever apply to a building that has not been built yet — an existing building can always be levelled, so nothing is held back for a requirement that does not exist. Every step the focus takes is written to the Activity log with the reason, so you can watch it work through the chain rather than guess.

Population floor

Build farm at population threshold is the standing version of the same idea: when free population drops to your Free population threshold, the profile's cities build nothing but the Farm until Farm levels to build are queued, then go straight back to the normal schedule. It stops a city quietly stalling with a full build queue and no room to recruit.

Automation overrides

Per profile: Turn off auto building, Turn off auto research and Turn off auto recruiting. These exempt one profile's cities while leaving the global switch on — and the schedule stays saved, so switching back resumes where it left off rather than starting from nothing.

Recruitment spells

On the Troops sub-tab. A spell is cast immediately before a recruit run so the orders are placed while the buff is up, and never re-cast while one is still active. From favour is the reserve to keep — favour is one pool per god shared by all your cities, so this is what stops one city draining it — and Free slots skips the cast unless the queue has room, because a blessing never reaches orders that are already running.

Move recruitment heroes sends a hero that makes these units cheaper or faster to a city before a long drive. A move takes hours and the bonus only applies to units queued after the hero lands, so it only fires when the drive will still be running well after arrival — and a hero already sitting in the destination is only replaced when another one is a better fit for what that city is building.

Moving a setup

Export writes the profile to a JSON file; Import reads one back, offering to Overwrite current profile or Create new profile. That is how you carry a proven setup to another world or share it with your alliance.

Decides from: the city's current levels and queues, your targets and priorities, and what the city can currently afford. Levels already in the queue count as built, so the same order is never placed twice. A target already met is skipped; a building that cannot be started yet waits rather than blocking the ones behind it.

City overrides

An override is a one-city exception to its profile, set from inside the game rather than the panel. Open a building in that city and you'll see a Grepoworks box with Override active, a Target field and a Queue.

• Buildings — press + to set a target level for that building in that city only.
• Research — press + on a research to put it first in the Grepoworks queue for that city.
• Troops — override counts are totals the city should hold, not a queue to add on top. Ask for 200 biremes in a city that already has 150 and it recruits 50. Override units are recruited before the city's profile targets.

An override outranks everything: while one is outstanding but unaffordable, the city holds its build slot empty rather than spending the resources on something nobody asked for, and the trade planner prefers override cities as receivers — so the resources come to it. That is also why an override you forget about will quietly park a city, and why Clear all exists: it removes the override and the city goes straight back to following its profile.

Trade

Auto-trade enabled moves resources between your own cities. It runs before each build, research and recruit pass, so a city that is short can be topped up in the same cycle it needs the resources — rather than sitting idle until the next one.

A city only gives when its own queues are full and it has surplus on top; a city only receives when it has open queues and genuinely cannot afford what is scheduled next. That pairing is what stops resources bouncing back and forth between two cities that both look "rich" from one angle.

Pool resources to target city

Emergency mode. Pool target is either an Own city or a Custom city (ally) by town ID. Pooling ignores the fill setting and full queues, keeping only the reserve % in donors — it is for when one city needs everything you have. Shipments still balance by remaining space per resource, so the target does not end up with three full wood loads and no stone, and it stops when the target is full.

Farm village trading

Farm village trading buys what a city is short of from the farm villages on its own island — a city can only trade with the island it stands on. Each village's rate starts at 1.25 and drops by a fraction per unit traded, recovering slowly over time. The bot trades the largest amount that still leaves the rate at or above your Minimum trade ratio, then moves to the next village; when no village on the island is above your minimum it stops and waits for the rates to recover. Minimum trade size stops it making trades too small to matter.

Decides from: what the receiving city actually needs for its own scheduled builds, research and troops — not just "who has least". Shipments are sized against the space each resource has left in the receiving warehouse, counting trades already in flight, so a send cannot overflow on arrival.

Newcomer quests

The introduction questline a new account is given. It lives at the top of the Island tab, and it is the first thing worth switching on on a fresh world.

Claiming rewards

Claim newcomer quest rewards collects a quest's reward as soon as that quest reports itself finished. Quests still running are never closed early — the bot only ever takes what the game already considers earned.

The same switch activates any advisor the game is offering for free. A free advisor only ever appears as a starting-quest reward, which is why it has no separate setting of its own. Only an activation the game itself marks as free is ever clicked; one that carries a gold price is never touched, so this cannot spend premium currency. The check stops entirely once no newcomer quest is still running.

Prioritize newcomer quests first

Whatever the open quest asks for — a building, a research, a unit — goes to the front of the starting city's queue. It is a priority, not a limit: the city keeps working through its own plan alongside, so a quest that wants a single unit or a hero placement never leaves it standing idle with full stores.

Two things follow from that. A quest asking for a unit is recruited even when Auto-recruit enabled is off — but only that unit, never the profile's own troop targets. And a city with no profile assigned yet falls back to growing its economy (Senate, farm, warehouse, the three resource buildings, market, academy, temple) so it keeps developing until you assign one.

What happens to the rewards

A quest reward is handed over the moment the quest is closed, and it cannot be stashed — anything past your warehouse cap is destroyed. So a reward made of resources waits until there is room for it rather than overflowing.

There is one deliberate exception. If a pending building, research or unit is genuinely short of one of those resources, and that resource still lands in full, the reward is taken and the spill on the others accepted — the need outweighs the waste. When nothing is waiting on them, the reward simply waits. A held reward is written to the quest log with the reason, so it is never silent.

Decides from: the quest's own reported state, its stated reward, your free warehouse space per resource, and the shortfall of the work already scheduled in that city. Favour and spell rewards are never held — only resources can overflow.

Island

Island quests are not here — they are on Culture & ✴️ Quests.

Farm villages

Auto-collect farm villages claims every ready village across all your cities, through the game's own API rather than by opening the overview window — so nothing flickers on screen while you play. Collection interval picks the loot timer: 5 minutes, 20 minutes, 1 hour 30 minutes or 4 hours.

A village is claimed ten seconds after its own timer expires, never before, and the timer for the next attempt starts after each pass whether it succeeded or not.

Expanding and taking villages

Expand farm villages on every island upgrades the villages you already own, up to the level set in Expand up to level (1 to 5). Expanding costs resources and raises what each village hands over, so it pays for itself on a world you intend to stay on.

Take farm villages that are not yours yet claims the villages you have not unlocked. Unlocking one costs battle points, not resources, and is only attempted once you actually have enough — otherwise the game refuses and the attempt is wasted.

Bandit camp

Auto-attack bandit camp (home island, until cleared) works through the camp wave by wave until it is cleared. It sends offence troops only — no swordsmen or archers, so your defence stays home. Rewards are stashed when there is room and applied immediately when there is not. Inspect bandit camp shows the current wave and cooldown without sending anything.

It also checks whether the city can actually beat the wave in front of it before sending anything. When it cannot, it waits and says so in the log rather than feeding troops into a fight they lose.

Decides from: the village's own timer and whether the receiving city has room. Collection is skipped only when wood, stone and iron are all at capacity — one full resource is not enough to stop it, since the other two are still worth collecting.

City Farms

Farming an inactive player on a loop. You add targets from the game, not the panel: tick Add to farmlist? in Grepolis's own attack window and press attack. The bot then repeats that exact attack every time those troops come home.

The threshold is the whole point: a target that comes back under-full has been picked clean, so hitting it again immediately wastes the trip. Resting it for a few hours lets it refill while your troops do something else. The table shows each target's Status: Active, Waiting for troops, Warehouse full or Checking loot.

Decides from: what the last run actually brought home against your capacity threshold, and whether the same troops are back. A target that changes owner is switched off automatically, so an inactive who came back — or got conquered by someone who will notice — is not hit by accident.

Culture & ✴️ Quests

Two automations that share one screen, because both are decided per city and both are set up in the same City List at the bottom.

Auto culture (per city)

Under Run these celebrations: tick any combination per city. A city with nothing ticked runs no celebrations.

The two resource celebrations only fire when the city has a surplus, so they never take resources a build, research or troop queue needs — culture points are gained from what would otherwise sit idle. Hold Victory marches once battle points ≥ is global: it keeps a reserve of battle points instead of spending every one the moment it appears. Set it to 0 to hold one whenever the game allows. Olympic games spends premium currency and keeps running until you turn it off — it is the one celebration that costs something you paid for, so it is never enabled by default.

Island quests (beta)

Island quests enabled handles a quest end to end — accept, pay or send whatever it asks for, and collect the reward. Cities on the same island contribute to the same quest together, so no single city has to cover the whole cost on its own.

Splitting it this way lets a front-line city take only the quests that cost nothing while a safe backline city takes the expensive ones — the reward lands in the same shared inventory either way.

What happens to the rewards

There is one spell inventory shared by all your cities, and only the spells island quests award are listed — long-term, alliance, event and bought spells are left exactly where they are.

Replace weaker spells when the inventory is full lets a new reward take the place of a weaker one of the same kind: an epic version replacing a rare one, or a longer reinforcement replacing a shorter one of the same unit. It only ever compares like with like — never a different unit, never an equal one — and never touches the extra inventory.

When the inventory is full and nothing can be upgraded, When it is full and nothing can be upgraded decides between Leave the reward unclaimed (it stays in the quest window for you), Use the new spell straight away, Spend the weakest stored spell to make room and Claim it and accept the loss.

Per-spell rules

Below that, every reward spell gets its own row reading do this — when that — to those: Store it, Use it when… or Leave it, a condition, and — when using it — whether that means Any city, One city or Cities on a profile. Conditions range from stock-keeping (at most this many already stored, at least this many free slots) through queue state (the build queue is empty, this many orders are queued, the barracks are idle) to the situation on the map (an attack is incoming, free population is at most, that resource is below, favour is below).

Press + to stack another line under a spell. Lines are read top to bottom and the first one whose condition fits is the one that runs; the ones below it are marked otherwise. That is how you say something like "use a building-speed spell when a city has three or more builds queued, otherwise store it — but if I already have four stored, use it anywhere". If no line fits, the reward is left alone rather than guessed at, so end a stack with Store it / always if you want a catch-all.

Decides from: for celebrations, the game's own Agora view for that city — whether it is actually startable, what it costs, and whether one of that kind is already running. If the game would grey the button out, nothing is sent, and the city is left alone until the running celebration ends. For quests: the quest's own type and side, your allowed types and refused costs for that city, and what the quest still asks for versus what your cities on that island can pay between them. A reward is judged at the strength it will actually have once the quest's difficulty is applied — not at its base value — so an upgrade is recognised as an upgrade.

Combat

Five sub-tabs: Timed Attacks, Timed Support, Incoming Defense, Timed Spells and Cave.

Timed attacks and support

Set these up from the game's own attack or support window: pick an Arrive at time and press Schedule. In the panel each row gets an Early tolerance (seconds) and Late tolerance (seconds) — the window the landing must fall inside.

Grepolis adds a random anti-timer of up to ten seconds to every launch, which is exactly what makes hand-timing hard. The bot sends, reads the arrival it actually got, and recalls the moment it falls outside your window — repeating until one lands inside it, then stopping. Tuning starts three seconds before the send; until then the row shows Tune start. Widen the tolerance and it finishes sooner; narrow it and it tries harder.

Every attempt ends in the Success Archive or the Failed Archive. Anything not locked in by the deadline is pulled back rather than sent late — a late attack is worse than none.

Import from attack planner turns every planned attack and support leaving your towns into scheduled sends in one press. The planner itself is never changed, so your alliance still sees the plan as you left it.

Incoming defence

Per city, under Incoming attack defense. A dodge sends your troops out on a late support run and recalls them so they return about ten seconds before the last incoming hit lands — out of the city while it is hit, home before the next wave. Militia is the alternative for cities you would rather not empty, fired shortly before the first hit. The dodge destination is Auto (your closest own city), Own city to choose, or Custom for any city ID — an ally or a ghost.

Auto backsnipe turns the dodge into a counter: the returning troops are timed to land right around the attack instead of just avoiding it. Return timing offers After incoming lands, Before colonization or After colonization, with a Return offset (seconds) and a Backsnipe send as choice of Support or Attack. A recall carries no anti-timer, so unlike a fresh send the return lands exactly where you put it.

Timed spells

Cast a spell at a set moment, on your own city or someone else's. Pick a City — or a Town ID for a target that isn't yours — then a Spell and a Cast at time, and press Add.

Cave

Auto silver → cave, enabled per city, deposits the fixed Silver → cave deposit amount (deposited when silver hits max storage) whenever a city's silver reaches maximum storage. Silver that would otherwise be mined into a full store is kept instead — and once it is in the cave it cannot be plundered. The tab shows Deposited by bot per city so you can see what it has banked.

Decides from: the arrival times of the incoming commands and your tolerance window — the last hit for a dodge, the first for militia, so both are timed against the wave rather than a single attack. A city with an accepted defend quest running is left alone, so a dodge does not cost you the quest.

Intel

Intel enabled builds a private picture of your neighbourhood. World data refresh (hours) sets how often to pull fresh world data, and Refresh world data now forces one. Data is fetched at most once per hour — that is a Grepolis limit, not a choice.

Three sub-tabs, each carrying its own settings:

• City records — open a battle or spy report in the game and press Index in the report footer to bank that city's troops, player and coordinates. A city that consistently sends one troop type earns a Label such as Light ship city, Harpy city or Offensive city, so you can tell at a glance what you are looking at next time.
• Activity Tracker — Inactive after (days, 0 growth) is how long points must stall before a player counts as inactive, and Auto-watch radius (current city) how far out to look. Everyone in range that qualifies appears under Watched players on their own; press Pin to keep one after it drifts out of range, or Unpin to let it go. A pinned player is measured from the moment you pinned it. You can also pin one straight from another player's city Info tab in the game, with Track activity.
• Ghost Cities — Ghost city radius (current city) sets the range; the table lists ownerless towns inside it with points and distance. These belong to players who quit the world, and can be taken with a colonization ship without a full conquest.

Decides from: both total points and attack points standing still for the number of days you set. Needing both is what separates a player who has stopped playing from one who is simply building quietly — someone whose total climbs while their attack points sit still is very much still there.

Activity

Five logs, each on its own tab: Activity log, Market log, Celebration, Quest log and Error log. Entries are colour coded by severity.

This is the first place to look when something has not happened. The log says what was done, to which city, and why the rest was skipped — a line like "skipped (one is already running here)" is the bot telling you it checked and chose not to act. It is also where a build focus shows its work: you can follow it levelling a Farm for population, then a Warehouse for space, then returning to the Academy.

In the error log, a blocker the bot expects — no resources, nothing to do, a full inventory — is muted; a request that actually failed is red. Clear empties a log. Logs live in your browser and are never sent anywhere.

Account

Shows your License code, Plan, Expires and Status. Use Change license code → Apply new code to move this browser onto a different licence — your settings and profiles stay where they are.

Seed base profiles loads the ready-made starter profiles (Light ships, Biremes, Conquest, Land defense) that aren't already in your list. Existing profiles are left untouched, so it is safe to press at any time.

Where it is offered, Enable beta version runs the latest beta build with new, less-tested features; turning it off drops you back to stable. The game page reloads to apply. A beta build is marked beta in the panel header, and some features — such as the IO Monitor under Intel, or the Attacking and Defending quest types — only appear there.

One licence covers one browser at a time, with no limit on how many worlds you run in it.

If something looks stuck

1. Open the Activity tab first. Most "it isn't working" turns out to be the bot reporting a condition — not enough resources, a target already met, or a celebration already running. A city that looks stuck on the Farm or the Warehouse is usually a build focus clearing a requirement, and will move on by itself.
2. Check the automation is on. Each feature has its own enable toggle, and cities have to be assigned a profile before anything happens to them. Check the profile's Automation overrides too — a profile can be opted out while the global switch is on.
3. Check the city is opted in. Celebrations and island quests are per city, in the City List on Culture & ✴️ Quests: a city with nothing ticked is deliberately left alone.
4. Refresh the game tab after an update. New versions install themselves, but the open tab keeps running the version it loaded with.
5. Still stuck? Press Report an issue in the panel header — it attaches the log for support — or use the livechat on this site.