Chart Indicator

Custom chart indicators for /trading

Build an indicator for the charting terminal. It becomes a picker entry with a generated settings dialog, a legend row and saved-layout persistence, with no build step and no restart.

This is the chart (JavaScript) path. It has nothing to do with the Python openalgo.ta indicators used from strategies, scanners and backtests: different language, different runtime, different API. If the request is for a Python indicator, this skill is the wrong one.

The one rule

Never write a file into strategies/indicators/ directly. That folder is imported by the live chart, and the runtime fails silently in the ways that matter most: a column that is one element short, or a plot key that does not match what calc returns, draws nothing at all and raises nothing anywhere.

Always: write to a scratch path, validate, install on a pass.

# 1. draft to a scratch file (never the indicators folder)
#    e.g. <scratchpad>/my_indicator.js

# 2. validate against the real openalgo-charts build
node .claude/skills/chart-indicator/validate.mjs <scratch>/my_indicator.js

# 3. only on PASSED, install it
node .claude/skills/chart-indicator/validate.mjs <scratch>/my_indicator.js --install

--install copies into strategies/indicators/ only when there are zero errors, and exits 1 otherwise. If validation fails, fix the draft and re-run. Do not install a failing indicator, and do not weaken the validator to get a pass. Report warnings to the user rather than silently accepting them.

Never run npm install for this. The full frontend tree is 560 MB across 521 packages; the validator needs two ES modules totalling 368 KB. It finds them itself, in this order: frontend/node_modules/openalgo-charts if a React developer already has it, then its own .cache/, then it fetches just that one package at the version pinned in frontend/package.json. openalgo-charts has zero dependencies, so that is one small download, about a second, cached after.

If the fetch fails (no network, npm unavailable), say so and offer the choice: fix connectivity, or install without the pre-flight check and rely on the chart's own validation, which reports the same structural problems as toasts when the indicator loads. Do not silently skip validation.

Recent changes worth knowing

The descriptor contract has only gained optional fields since this skill was written, so an existing indicator keeps working on the pinned build. What changed, newest first:

• 2.5.2 to 2.6.0: seven more built-ins, a timeframe on 29 of them, and a wider descriptor. Every existing descriptor keeps working, and all twelve examples below pass the validator on 2.6.0 unchanged. The index below grew from 387 names to 433 and lost none.

  2.6.0. zigzag, high-low-52-week, zlema, vidya, elder-ray, schaff-trend-cycle and volatility-squeeze take the registry to 112, so a custom file that already used one of those ids now overrides it (pitfall 13). Twenty-nine built-ins (most averages, the bands, supertrend, atr, rsi, macd, stochastic, cci, adx and others) gain an input { key: 'timeframe', type: 'interval', default: '' }: indicatorDefaults() of those now includes timeframe: '', their calc folds to a timeframe set there, and a descriptor that copies their inputs copies a row only their calc honours (pitfall 24). withTimeframe(descriptor) gives your own study the same input. Every built-in now rounds a fractional window length (14.5 reads as 15); the exported helpers still do not, so coerce before calling sma and friends (pitfall 6). An alert's when and message run once for each bar a pass appended, each seeing the bars and values through the bar it judges. On a reload, a study whose first pass throws IndicatorInputError comes back in its error status, while any other throw still stops the restore. /trading has the chart apply Heikin Ashi, Renko, range bars, line break, point and figure and Kagi itself, so on those chart types a study's calc receives the elements drawn with ctx.transformed set, unless the trader sets its Compute on row to Underlying bars, when it receives the time bars and its values are read onto the elements; its hooks still run on the elements, indexed by element (pitfall 20). chart.on is typed from ChartEventMap: an event of your own is declared into it with declare module 'openalgo-charts', and chart.emit is deprecated for 3.0.0.

  2.5.4 to 2.5.8. Optional fields, all usable here unless noted: an overlay: true or plot: key target on a draws() shape or a marker, which is how a study in its own pane puts a signal under the candle's low; font, size, emphasis and alignment on labels, box captions and marker text; curve: 'smooth' on a polyline; tooltip, spans and font fields on table cells, and a tables() hook for several named grids; gradient, gradientBy and colorBy on a fill; frequency on an alert (all 2.5.4). New helpers crossesAbove, crossesBelow, crosses, rising and falling read a missing value as no signal, which is pitfall 4 done for you. What the library has and /trading does not take is in pitfall 25: the input types symbol, session, multiline, price and timestamp (2.5.4), visibleWhen, activeWhen and inline on inputs, and background returned as a list of targeted columns (2.5.6). 2.5.8 gave sixteen built-ins a calcTail that a spread does not copy. 2.5.4 and 2.5.5 corrected several calculations around missing data, and HMA at odd lengths, so a study measured against a built-in re-derives its expectations.

  2.5.2, 2.5.3, 2.5.7, 2.5.9 and 2.5.10 changed nothing an indicator declares. From 2.5.10, text markers on neighbouring bars are laid out in lanes instead of overlapping, and roc and williams-vix-fix carry new display names, so match a built-in by id, never by name.

• 2.5.1: a finished alert can stop drawing its line. Nothing an indicator declares changed and no export was added or removed: the index below counts the same 387 names it counted on 2.5.0.

  AlertControllerOptions.spentLines: 'hide' makes a triggered or expired alert keep everything except its line: the record, the scope, the checkpoints and the saved runtime all stay, which is what keeps a once-only alert from re-arming on the next reload. It is opt-in per controller, it is not written into an alert document, and the default is still 'show'.

  A host API, like hovered() and snapPrice() before it. An indicator never reads it and never declares anything about it.

• 2.5.0: tables that fit their text. Nothing an indicator declares changed and no export was added or removed: the index below counts the same 387 names it counted on 2.4.8.

  The one thing worth knowing for a descriptor: ChartTableOptions.cellWidth accepts 'auto'. A column then measures itself from its widest cell, using the font actually drawn, so a per-cell font override or a bold heading is accounted for rather than guessed at. An empty automatic column keeps a 28 px minimum, and percentage widths keep their measured proportions. Every cell also clips its text now, so a long reading can no longer spill over the column beside it, which is what made a wide value in one row look like a value in the next.

  AlertController.hovered() and Chart.snapPrice(paneIndex, price) also arrived. Both are host APIs: an indicator never calls either.

• 2.4.8: grab to pan, and a README rewritten. Nothing an indicator declares changed and no export was added or removed: the index below counts the same 387 names it counted on 2.4.7. Pressing and holding the plot now shows a grabbing hand and pans both axes, and mouse and pen panning stop the moment the pointer is released, while touch keeps its flick. The default covers both axes; a chart with a saved horizontal-only preference keeps it until somebody changes it in the chart navigation settings.

  The one thing worth knowing for a descriptor: a clickable legend action keeps its pointer cursor and stays usable across a repaint, which is the behaviour a hasSource braces button and a gear depend on. If a legend action of yours stopped responding after a redraw on an older build, that is what was fixed.

• 2.4.7: an alert's line can be dragged. Nothing an indicator declares changed. A price or study-threshold alert line is draggable by the trader, and a study threshold drags on its own plot's scale rather than the instrument's, including an independent or left scale. Worth knowing for a descriptor whose plot owns a scale: the preview does not enlarge autoscale and never shows study units on the price axis. The on-chart badge for an armed alert reads "Alert"; the serialized lifecycle values are unchanged, so anything reading alert.state is unaffected.

• 2.4.6: source access, marker anchoring and a legend that reads. Three optional descriptor fields, all of which an existing indicator can ignore. hasSource: true puts a braces button on the legend row beside the gear and emits indicatorSource with { instanceId, indicatorId, paneIndex }; the host owns the code and decides what the button opens, so set it only for a descriptor whose source a host can actually show. markerAnchor: 'price' measures a marker's aboveBar and belowBar against the instrument's candles rather than the descriptor's own first plot, which is what a buy or sell signal on an overlay means: below is below the low. The default stays 'plot', so a mark that belongs to a line keeps sitting on the line, and the field is ignored on a study that owns a pane. Legend readings now skip a plot drawn in a fully transparent colour, which matters if you declare an invisible column to anchor markers or fills to: it no longer reserves the width of a price in the row. Legend glyphs also scale with their button rather than the row's text, and ChartOptions.legendIconSize sets that button across the chart.

• 2.4.5: optional open interest and host contracts. The published build has 105 built-ins, including open-interest, open-interest-change and open-interest-buildup. Bar.oi is an optional reading: preserve zero, keep missing readings as gaps, and never sum OI when folding bars. securitySeries exposes a nullable oi column. Capability comes from host instrument metadata, not from whether one bar has a reading. See reference/api.md for an example. Host trader alerts can target a study's stable instance id and plot key; keep those plot keys stable and distinguish these alerts from descriptor alerts. The host owns delivery and pauses trader evaluation during loading and replay. Instrument, ReplayGroup, exportChartDataCsv and trading capability helpers are host APIs, not a reason for a study to mutate the chart, control replay or submit orders. Workspace/template APIs live in openalgo-charts/workspace, outside the core-plus-indicators object handed to a custom module. Existing descriptor fields remain compatible. Calculate from the supplied bars so a replayed study cannot reveal later history.

• 2.4.0: the constructs a ported study most often could not express. Every item is optional and needs openalgo-charts 2.4.0 or later installed; the validator checks against the installed build, so read node -p "require('./frontend/node_modules/openalgo-charts/package.json').version" before using any of them, and do not use them on an older pin. securitySeries(bars, interval, opts) folds the chart's bars to a higher timeframe, one value per bar, with the three readings named (as it stood at that bar, the default; offset: k for the last completed bucket; lookahead: true for final values, which repaints) and session: '0915-1530' to anchor sub-day buckets to the session open. It replaces every hand-rolled fold. plot.offset paints a column that many bars ahead, the tail landing in the right margin, with fills and the legend following. A calc that throws once installed is reported on the study's data status instead of thrown into the render loop; throw IndicatorInputError for a condition the user can fix. alerts[].message may be a function of the firing bar. Marker shapes cross and xcross, positions paneTop and paneBottom, pinned to the plot's edges. fills[].overlay for a band drawn on the price pane. plot.colorParts for a wick and border coloured apart from the body. tooltip and id on draws() labels and boxes. Inputs interval and time. table options fontSize: 'auto'. And ctx.requestBars on the attach context for another instrument's bars, which /trading serves from the terminal's own cached feed: the same broker session and the same bar cache the chart uses, so a benchmark costs no second transport and no credential reaches a chart setting. Omit exchange to mean the chart's own. It rejects on a host that registers no provider, and a study should publish that as unsupported rather than invent a value.

• 2.3.0: charts can be arithmetic over several instruments. openalgo-charts/transform gains parseExpression and evaluateExpression, so /trading can chart NIFTY/RELIANCE, 2*CE25000 - CE25200 or any expression over any number of legs. These belong to the transform tier, not to the API object a custom indicator module receives, so nothing about writing an indicator changes. Worth knowing for one reason: a study added to a computed chart runs on the folded series, whose bars have no volume and whose high and low are a bound rather than a measurement unless the host asked for close-only. Volume studies read zero there, which is honest rather than broken.

• 2.2.1: inputs can carry help text, and a plot can label its own axis. Every IndicatorInput variant now takes an optional tooltip, which the settings dialog renders as a small focusable ? beside the label. Put the explanation there rather than in a parenthetical that stretches the row. IndicatorPlot now takes an optional priceFormat, the same PriceFormat union addSeries uses, with a new percent variant: it suffixes the value and does not scale it, so a study returning 0..1 reads 0.62% and one returning 0..100 reads 62.24%. Multiplying inside calc to make the axis read better would change the legend, the crosshair and everything computed off the value. Like style.precision it belongs to a plot that owns its pane. Both fields are optional, so an existing descriptor is unaffected.

• 2.2.0: hosts can offer 85 drawing tools. The draw tier adds channels, pitchforks, Fibonacci and Gann geometry, wavefronts and manual patterns. ADVANCED_LINE_TOOLS, ADVANCED_GEOMETRY_TOOLS and PATTERN_DRAWING_TOOLS belong to openalgo-charts/draw; they are not part of the custom indicator's API object. The indicator descriptor contract and its 102 built-ins are unchanged. Drawing documents retain version 2 and existing tool IDs.

• 2.1.9: chart hosts gain built-in branding and an optional text watermark. ChartOptions.branding defaults to the OpenAlgo mark, while ChartOptions.watermark defaults off. Hosts can update them with setBranding and setWatermarkOptions, inspect them with brandingOptions and watermarkOptions, and follow branding changes through branding:changed. Blank watermark text follows the symbol and interval from setDataContext. The public types are LogoWatermarkOptions, ChartWatermarkOptions, and BrandingChangedEvent. These are host APIs and do not change or belong inside an indicator descriptor.

• 2.1.8: navigation can ease automatic price ranges as it reveals new extrema. animAutoscale follows animZoom by default, while a manual scale and a descriptor's fixed range() remain authoritative. Normalized wheel and trackpad gestures and the packaged widget's responsive controls are host features; they do not change a descriptor. OpenAlgo /trading constructs a bare Chart, so it receives the engine gestures but keeps its own toolbar, rails and panels rather than receiving WidgetOptions.mobile controls.

• 2.1.7: hidden indicators remain hidden through layout restoration and style edits. Reference levels now follow the instance's visibility along with its plots and other visuals. The new ChartObjects inventory also exposes an indicator's visibility and Tier-2 data status to host and widget object panels, but it does not change the descriptor contract or add work to a custom indicator.

• 2.1.6: Tier-2 studies follow the chart's data context and loaded source range. createTier2Indicator receives dataContext with the host's symbol, exchange and interval, cancels obsolete fetches, extends history when older bars arrive and refreshes when the host changes instrument. A descriptor can use supports(ctx) to report that its provider cannot serve a context. The managed lifecycle publishes loading, ready, empty, unsupported and error states with an explicit retry action, so provider failure is visible without putting network state into calc. Existing Tier-2 descriptors get the range, cancellation and status behavior through the wrapper without changing shape.

• 2.1.2: a Tier-2 study's data requests are keyed by data setting. Changing the symbol or any other data input clears the previous values immediately, and a response that arrives for the setting you just left cannot land on the new one. A style-only change reuses the history already in flight instead of refetching, and a live observation wins over a historical point for the same time. An attach that used to guard against its own stale responses no longer has to.

• 1.8.9: precision is keyed on the pane, not the descriptor. An onchart plot prints at the instrument's tick; a plot on its own pane prints at that pane's span with a floor of two decimals. A study pane is no longer formatted in the instrument's tick, which is why an RSI reads 70.00 rather than 70.0. Custom descriptors get this with nothing to declare, and a precision input is still the wrong answer. See Do not, below.

• 1.8.4: calc runs once per animation frame, not once per tick. A data update marks the indicators stale and the flush happens before the paint, so a burst of ticks collapses into one call. calc must therefore be a pure function of (bars, settings). It always had to be, but running per tick used to hide an indicator that counted its own calls or accumulated into store. Reading chart.indicators() or an instance's values() flushes first, so a read-after-update in the same turn still sees fresh numbers.

• 1.8.4: calcTail is rarely worth it now. The tick-rate problem it existed to solve is gone. It only pays when one pass over the loaded history is itself slow, which means deep history, not a fast feed.

• 1.8.3: the catalogue went from 91 to 102 built-ins, so a file written earlier can shadow an id that did not exist when it was named. The new ids are listed in reference/pitfalls.md under the collision entry. That release also corrected nine built-ins and moved ten defaults, so an indicator that compares itself against a built-in may need its expectations re-derived rather than assumed unchanged.