# ThetaGang: an IBKR options bot that sells puts against a target allocation

> ThetaGang is a Python trading bot for Interactive Brokers that writes puts and covered calls around a configured portfolio allocation. It is configurable, account-level in its decisions, and carries the risk profile of an options-selling strategy rather than a passive index fund.

**brndnmtthws/thetagang** — ThetaGang is an IBKR bot for collecting money

- Repository: https://github.com/brndnmtthws/thetagang
- Stars: 2,731 · Forks: 396
- Language: Python
- License: AGPL-3.0
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/brndnmtthws-thetagang

## What ThetaGang automates, and who it is actually for

The repository describes ThetaGang as an IBKR trading bot that started as an implementation of The Wheel strategy and grew into a broader portfolio automation tool. The problem it addresses is mechanical: an investor has a target allocation, and the bot tries to acquire that allocation by writing puts rather than buying shares outright, then rolling those positions and eventually writing calls when shares are assigned.

The intended user is someone who already trades options and wants the repetitive parts handled on a schedule. The README says normal usage is to run the script as a cronjob on a daily, weekly, or monthly basis according to your preferences. That framing matters. This is not an interactive app. It is a batch process that wakes up, inspects the account, and places orders.

The default configuration is described as a diversified portfolio with SPY at 40 percent, QQQ at 30 percent, TLT at 20 percent, and smaller positions in individual stocks. The README positions this as a starting point rather than a recommendation, and notes the strategy reduces risk while possibly limiting gains from large market swings.

The project ships under AGPL-3.0-only, which is unusual for a personal trading tool and worth understanding before you build anything on top of it.

## How the put-writing loop and roll logic work

The mechanism is straightforward once you separate it into steps. The bot reads your target weights from thetagang.toml, compares them against what the account holds, and writes puts when conditions are met: config parameters pass, buying power is adequate, acceptable contracts exist, and enough shares are still needed.

Open option positions are rolled indefinitely, with one stated exception: in-the-money puts, though the README notes this behavior is configurable. Once puts go in the money, they are ignored until expiration and exercise, after which you own the underlying. The roll logic has a guardrail worth noting: when rolling puts, the strike of the new contracts is capped at the old strike plus the premium received, which the README says exists to prevent the account from blowing up through over-ratcheting buying power usage.

After assignment, the bot switches from writing puts to writing calls at a strike at least as high as the average cost of the shares held. If you do not want every share covered, write_when.calls.cap_factor limits the number of calls, with 0.5 meaning 50 percent of shares held.

Deep in-the-money calls get special treatment. The bot prefers to roll them to the next strike or expiration rather than letting shares be called away, but the README warns that without adequate buying power the options may be exercised instead, restarting the cycle, and notes possible tax implications it does not cover.

## Installing ThetaGang and running a first configuration

The project publishes to PyPI and to Docker Hub, and pyproject.toml declares a console script named thetagang. Python support is declared as 3.11 up to but not including 3.15. The Dockerfile shows the image is built on a JDK base because it bundles IB Gateway components and IBC, the tool that automates gateway login.

For a local install, the package name is thetagang. The README does not spell out a pip command in the text available here, so treat the package name as the entry point and check the PyPI page for the current invocation.

The configuration file lives at the repository root as thetagang.toml. The README points to it as the place to adjust parameters, and the default allocation is the SPY, QQQ, TLT mix described above. One config key the README names explicitly is write_when.calculate_net_contracts. Setting it to true tells the bot to compute contracts on a net basis, which is what you need when running strategies such as PMCCs or stock replacement where long legs are managed by you and only the short legs are executed by the bot. The README is clear that ThetaGang will not manage long positions for you.

```toml
write_when.calculate_net_contracts = true
```

After a first run, the README's own advice is to consider paper trading before committing capital, which is the sensible way to confirm the bot is reading your account and config the way you expect.

## One account per strategy, because decisions are account-level

The most useful operational warning in the README is about running multiple strategies in one account. ThetaGang's decisions are account-level. Buying power usage, position targeting, rebalancing logic, option rolls, cash management, and hedge logic all see the same combined portfolio, and the README states they can interfere with each other in ways that are hard to reason about.

The recommendation is separate IBKR accounts, for example separate linked sub-accounts, each funded independently. The stated benefits are cleaner risk boundaries, cleaner performance attribution, fewer cross-strategy side effects, and easier debugging. That is a real constraint on how you deploy the tool, not a stylistic preference. If you want to run a conservative wheel strategy alongside an aggressive hedge overlay, the bot will not keep them apart for you.

## The assumption that makes or breaks the strategy

ThetaGang is built on one statistical premise, and the README states it plainly: implied volatility is typically higher than realized volatility on average, so selling options harvests that gap. The README also states the failure case with equal clarity. In cases where implied volatility is not higher than realized volatility, the strategy will cause you to lose money.

That is the honest framing of the trade. You are being compensated for taking on real financial risk, and the README's risk disclaimer says selling naked puts has theoretically unlimited downside if the underlying goes to zero. It also warns that losses can exceed your initial investment.

The optional features listed in the README (direct share rebalancing, cash management through a cash-equivalent fund, VIX call hedging, long-put tail hedging, regime-aware rebalancing gates, external decision providers, exchange-hours enforcement) are risk controls layered on top, and each can be enabled or disabled independently. They do not remove the underlying premise. If you disagree with the premise, no amount of configuration fixes the strategy.

## How ThetaGang differs from a passive allocation tool

The natural alternative is a plain rebalancing script or a robo-advisor that buys shares to hit target weights. The difference is which side of the options market you sit on. A passive tool buys the underlying at market and accepts the market return. ThetaGang writes puts instead, collecting premium while waiting to be assigned, and accepts assignment at the strike rather than at whatever price the market offers.

That changes the failure mode. A passive allocation tool underperforms in a drawdown but owns the shares at averaged cost. ThetaGang can be assigned at strikes above the current market price, meaning you own the same shares at a worse basis, and then it writes calls at a strike at least as high as your average cost, which caps the recovery. The README acknowledges this trade-off directly when it says the strategy reduces risk but may also limit gains from big market swings.

The other difference is operational. A rebalancing script can run almost anywhere with an API key. ThetaGang needs a live IBKR connection through IB Gateway, which is why the Docker image bundles a JDK, IBC, and an X virtual framebuffer. That is a heavier deployment than most portfolio scripts, and it is the price of automating a broker that expects a desktop gateway session.

## Maintenance, licence, and what you take on by running it

The repository is not archived, and the most recent push recorded is 2026-09-28. The latest release in the list is v2.1.0 from 2026-08-29, following v2.0.2 and v2.0.1 earlier in the year. The pyproject.toml version string is 2.1.1, which is ahead of the last tagged release, so expect the packaging metadata and the release tags to drift slightly.

The dependency list is not trivial. It includes ib-async for the broker connection, SQLAlchemy and Alembic for persistence and migrations, pydantic for config validation, exchange-calendars for market hours, and numpy. Alembic migrations mean the on-disk database schema can change between versions, so upgrading is not just a pip install. Back up the data directory before you move versions.

On licensing, the project is AGPL-3.0-only. That is a strong copyleft licence with a network clause. If you run a modified version as a service other people interact with, the AGPL's source-availability terms are generally understood to apply. This is not legal advice, and if you plan to build a product on top of the code you should get proper advice rather than relying on a summary. For personal use on your own brokerage account, the practical effect is that you must pass on the same licence if you redistribute.

## Conclusion

Adopt ThetaGang if you already run IBKR, understand short-option mechanics, and want a configurable bot that writes puts against a target allocation. Do not adopt it if you want a passive index position, if you are unsure how assignment works, or if you cannot fund a dedicated account for a single strategy. Before running it live, set up the IB Gateway connection, read the risk disclaimer in the README, and confirm that thetagang.toml matches the allocation you actually want, because the bot's decisions are account-level and will act on whatever buying power it sees.

## FAQ

### What is ThetaGang and what does it do?

ThetaGang is an IBKR trading bot, written in Python, that started as an implementation of The Wheel strategy and now handles portfolio automation such as direct share rebalancing, cash management, VIX call hedging, and exchange-hours gating. It tries to acquire a target allocation by writing puts, rolling open positions, and writing calls after assignment.

### Is ThetaGang good for beginners?

The README's risk disclaimer says options trading involves substantial risk and is not suitable for all investors, and it advises considering paper trading first and consulting a financial advisor if you are unsure. It also assumes you understand assignment, rolling, and buying power, which are not beginner topics.

### What are the best ThetaGang strategies?

The default configuration is a diversified allocation of SPY at 40 percent, QQQ at 30 percent, TLT at 20 percent, plus smaller individual stock positions, and the README calls it a good starting point. The README also says that if you want materially different strategies you should use separate IBKR accounts, because decisions are account-level.

## Sources

- [brndnmtthws/thetagang on GitHub](https://github.com/brndnmtthws/thetagang)
- [Issues](https://github.com/brndnmtthws/thetagang/issues)
- [License: AGPL-3.0](https://github.com/brndnmtthws/thetagang/blob/main/LICENSE)
- [README](https://github.com/brndnmtthws/thetagang/blob/main/README.md)
- [Releases](https://github.com/brndnmtthws/thetagang/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/brndnmtthws-thetagang